--------------------------------------------------------------------------

XWarp 1.00 README - October 1993

The files in these directories are the source for XWarp 1.00 for Linux.

XWarp is a program that allows warping of an image in GIF format.
The user can define 2 grids (made up by deformable rectangles):
a SOURCE grid and a DESTINATION one, then the program makes the work
just pressing a button! 

The algorithm for warping has been written from scratch, while the routines
for handling GIF images are from the Gershon Elber giflib package.

This code is absolutely free.
The only thing that we ask you is to e-mail us if you try this program:
let us know your comment! (even if you use it only for some minutes
and then 'rm -f *' in the XWarp-1.00 directory!)

In the tar file there is an executable xwarp which has been compiled under
LINUX 0.99pl13 with XView3 (with the -m486 option, but it shuld go even on 
a 386, if I'm not wrong; just try!).

The program REQUIRES the XView library to run (it's just a nice toolkit!)
The XView package which comes with SLS (I've tryed 1.02 and then 1.03)
works fine. However I suggest to install the new XView 3L5.1 package
(tsx-11:/pub/linux/binaries/usr.bin.X11/xview3L5.1.tar.gz or
 sunsite:/pub/Linux/libs/xview3L5.1.tar.gz) which fixes some bugs, 
especially if you plan to use the toolkit!

INSTALLING xwarp:

 - type 'zcat XWarp-1.00.tgz |tar xv ' in your working directory.
   tar will create the XWarp-1.00 directory for you.
 - the rest is obvious...

COMPILING xwarp:

- You need the libgif.a file in your lib directory (I say /usr/lib )
  It should works even on 386. However you can easily recompile it
  just typing 'make' in the GIFLIB directory, then move it to /usr/lib
  (you can move it in the directory of XWarp, but then you have to change
  the Makefile for xwarp adding the flag -L. )
- Tune the Makefile for your machine (386 or 486)
- Then type 'make' in the XWarp directory.
  No matter for some warnings from xwarp.c (;-)))
  
RUNNING xwarp:

- Just type xwarp with no arguments (if any it will be ignored!).
- You'll have in a few seconds a window with a nice bar with pop-up menu 
  and buttons and two lines of status for the GIF file and the grid.
  Here is a description of each menu and button:
File (menu)
	Open: Prompts you with a frame for typing the name of the GIF
	image to be opened
	Quit: just quit with confirmation
'Source grid' (button)
	It's a switch button for passing from the Source to the Destination
	grid. At each press the button label changes (Source/Destination)
Grid (menu)
	New grid: prompts you with a frame for inserting the grid parameters,
	that is X and Y granularity(=number of rectangles for X and Y)
	This requires first that you load an image
	Load grid: load a grid previously saved
	Save grid: save the current grid 
Warp (button)
	Just realizes the warp from the source grid to the destination.
About (button)
	try yourself!

USE OF THE MOUSE:
 
-Under XView when you click with the Right Button on a Menu it will roll
 down, while clicking on it with the Left Button will cause the Default
 Menu item to take effect (usually the first menu item)

In the image window:
- RIGHT BUTTON: toggle the color of the grid (White or Black)
- MIDDLE BUTTON: Hide/Show the grid
- LEFT BUTTON: Move a crosspoint of the current grid (the cursor will
	change to diamond cross when you are near a crosspoint)
	Click once for fixing the point, then click a second time in the
	point you want to move the crosspoint.
	NOTE: the program currently does not check the limits of the
	area in which is reasonable to move a crosspoint (i.e. to maintain
	the areas with no intersections), so you can move a crosspoint
	wherever you want, but the result is impredictable!

Enjoying the example:
 - Open the 'portrait.gif'
 - Load the grid 'port_source.grd'
 - Click on 'Source grid' button to toggle to the destination grid
 - Load the grid 'port_dest.grd'
 - Just press 'Warp' and enjoy.
 - It's amusing to hide the grid (MIDDLE button) and then to press
   the Source/Destination button to see the effective change (;-)))

In the tar package are provided some images for trying: amuse yourself!
Note that the program does not save the GIF just warped; it's easier to
Grab the window with XV, also because the noise added by the warper
could be smoothed by XV itself and then to save the warped image in
whichever format you prefer.

TODO
 - Possibility of non uniform grids
 - Check the destination point when moving a crosspoint
 - A man page (if useful)

THANKS
	To Gershon Elber for the GIF library: it works fine!

FINAL NOTES:
 - Sorry for the English!
 - e-mail suggestions/comments/BUGS to calamaro@dist.dist.unige.it
   (do not ask us what led us to make xwarp...)

Have fun!
			Luca, Guido and Roberto.
			 calamaro@dist.dist.unige.it

===========================================================================

