gimp/plug-ins/gfig/README

GFig
~~~~

Andy Thomas (alt@picnic.demon.co.uk).
http://www.picnic.demon.co.uk. 

Release 1.2  16.3.98
~~~~~~~~~~~~~~~~~~~~

Change summary from 1.0
~~~~~~~~~~~~~~~~~~~~~~~
Bug fixes + removed warings unless in debug mode. Fix gtk warning
when creating new fig object is cancelled.

Release 1.0  6.3.98
~~~~~~~~~~~~~~~~~~~

Change summary from 0.96
~~~~~~~~~~~~~~~~~~~~~~~~
Changes only to allow compiling with version 0.99.4 of gtk.

1) tooltis api has changed. Made the required changes.

Release 0.96 3.2.98
~~~~~~~~~~~~~~~~~~~

Change summary from 0.95
~~~~~~~~~~~~~~~~~~~~~~~~
Only a few changes.

1) Updated to work with version gtk+0.99.3
2) New grid type (isometric). Thanks to Rob Saunders (rob@arch.usyd.EDU.AU) 
   for this patch.
3) Cleaned up code to work on HP-UX system. 
   (Thanks to "Rafael E. Herrera" <raffo@neuronet.pitt.edu> for those patches).


Release 0.95 14.11.97
~~~~~~~~~~~~~~~~~~~~~

Change summary from 0.9
~~~~~~~~~~~~~~~~~~~~~~~
See below for details.

1) More object types:-

* Spiral
* N pointed star (N >=3 )
* Simple Bezier curves (see below)

2) Refined control:-

When "snap to grid" is active then using the third mouse button will cause
the point to be constrained to horz/vert (rect grid) or radius/radial 
(polar gird).

3) Proper brush preview.

4) All brush types can be used including "painting with a pattern".

5) Painting methods now include selections.

6) Objects can now be filled with a pattern/colour (using selections+fill).

7) Can "reload" background image while Gfig is running

8) Possible to show X/Y pos.

9) Can limit display to single object in the collection. (see below for more 
details).

10) Bug in GDK/GIMP interaction work around. Should now work on SGIs/Suns
with multiple screen depths.

This is the second public release of GFig plug-in for the GIMP.

With this plug-in you can created vector graphics and "render" them using the
GIMPs painting functions. The vector graphics stuff is some what akin to those 
found in xfig but not as advanced (I have not used any code from xfig - didn't 
even look at the source when trying to figure out some of the maths).

I have not attempted to implement features that are
already present in the GIMP itself.

Patch file
++++++++++
*************************************************
ONLY required for GIMP <= 0.99.14
*************************************************

All released up to and including 0.99.14 contain a bug in the paintbrush.c code.
I have submitted a patch to correct this fault. If you have NOT applied 
this patch then in the source code you MUST REMOVE the following line form 
the start of the source file:-

#define HAVE_PATCHED 1

The patch is included at the end of this README.

This define will be removed when the patch is integrated into the GIMP release.

The current version of the GIMP (release 0.99.15 at time of writing) does
NOT require this patch.

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 colours 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 colour. 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 colour).
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 GIMP - 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 GIMPS pencil. 

Airbrush
~~~~~~~~
As GIMPS 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 GIMP 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 ~/.gimp/gimprc 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 the GIMP).

 
Installation
++++++++++++

Simply build(see INSTALL) the Gfig object and install it in your 
plug-in directory. 
The program can be found under the following option.
The program is distributed as a single "C" source files - hopefully
makes building easier.

	<Image>/Filter/Render/Gfig.

In common with a number of other plug-ins Gfig uses an entry in the gimprc file
to specify a directory to search for groups of objects. If this entry is absent 
or unreadable a warning dialog will appear. To remove this warning create the 
directory "gfig" in your gimp directory and add the following to 
your .gimp/gimprc file:-

(gfig-path "${gimp_dir}/gfig")

The distribution contains a number of example figures. (Copy the contents
of gfig-examples to a directory on gfig-path or use the "Rescan" button).

I have only managed to test this on Linux (8bit + 16bit displays). It should
port to other platforms. (I am a little concerned over the rint() function
- not sure which other systems have this).

INSTALL
+++++++

A number of people had problems compiling Gfig. I have released it a a single "C"
file in the hopes it makes building it easier. I use the following
simple shell script to compile/install Gfig.

Invoke the script as 

	ccgimp gfig

--- Shell script ccgimp start ----
:

LD_LIBRARY_PATH=/usr/local/lib

export LD_LIBRARY_PATH

# Compile a gimp program.

cc -o $* $*.c -lgimp -lglib -lgdk -lgtk -lgimpui -L/usr/X11/lib -lXmu -lX11  -lm 

if [ $? -ne 0 ]; then 
exit 1
fi

cp $* ~/.gimp/plug-ins/

--- Shell script end ----

Problems?
+++++++++

If you have any problems with this plug-in please mail me 
(alt@picnic.demon.co.uk) and I will try to help.


TODO 
++++

Some random ideas your thoughts welcome (no order implied & I might never
get around to doing them!):-

1) Allow objects to be drawn with different brushes. (0.95 - Can be done 
by selecting each object one at a time and changing the brush).
2) Rotate objects (but you can do this in the GIMP?).
3) More object types (spiral, helix, .....).(0.95 - Added spiral/bezier/star)
4) Scale individual objects. (Still on todo).
5) Some type of "Tab" through selection of objects. (0.95 - Done)
6) Preview window for brush selection.(0.95 - Done)
7) Expand the drawing area (add scroll bars?)
8) Pointer locations (x,y) indicator.(0.95 - Done)


Let me know if you find this plug-in useful.

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!!!)


PATCH ONLY REQUIRED FOR GIMP <= 00.99.14
++++++++++++++++++++++++++++++++++++++++

Apply to paintbrush.c in gimp*/app directory. Long ago this was a bug in 
another form! (See my web page on the script-fu script I wrote.)

--- paintbrush.c.orig	Tue Oct 14 23:15:15 1997
+++ paintbrush.c	Tue Oct 14 23:15:59 1997
@@ -323,7 +323,6 @@
       non_gui_paint_core.startx = non_gui_paint_core.lastx = stroke_array[0];
       non_gui_paint_core.starty = non_gui_paint_core.lasty = stroke_array[1];
 
-      num_strokes /= 2;
       if (num_strokes == 1)
 	paintbrush_non_gui_paint_func (&non_gui_paint_core, drawable_id, 0);