NAME

<h1>NAME</h1>

<em>xmorph/morph/tkmorph/gtkmorph</em>: image warping and dissolving (morphing) programs

alltogether they form the Xmorph project, available at  http://xmorph.sf.net

<h1>NEWS</h1>

In sep 2000, the <em>Xmorph project</em> has been completely reorganized
to use the autoconf/automake. Please read the "THE NEW PROJECT"
section.


<h1>AUTHORS</h1>

xmorph/morph/tkmorph/libmorph:
  Written and Copyright (C) 1994-2000 by Michael J. Gourlay <br>

gtkmorph/libmorph:
  Written and Copyright (C) 2000-2004 by A C G Mennucci

<h1>LICENSE</h1>

The <em>Xmorph project </em> is free software; 
you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version. <br>

It is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details. <br>

You should have received a copy of the GNU General Public License
along with Xmorph; see the file COPYING.  If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.


<h1>DESCRIPTION</h1>

These are digital image warping programs, also known as
"morphing" programs.

These programs read, write, warp, and dissolve images, and read,
write, create, and manipulate control meshes which determine the
warping.  xmorph and tkmorph have help pages built into them, so no
external documentation is necessary. gtkmorph has a runtime guide.

<h2> libmorph </h2>

this library offers basic services of morphing and mesh editing

<h2> xmorph </h2>

xmorph runs under the X Window System, using the X library, X toolkit,
X miscellaneous utilities, and the Athena widgets, all of which are
publically available from the Open Group Inc., and part of the typical
X installation.  Xmorph also runs under Microsoft Windows NT and
Windows 95, if you also have an X server and X libraries such as
cygwin.

xmorph is a GNU program.

<h2> gtkmorph </h2>

gtkmorph is another graphical interface for the warping engine libmorph;
gtkmorph uses the gtk+ , gdk and gdk-pixbuf libraries;
you may find these in  ftp://ftp.gnome.org/pub .
Gtkmorph is also more evolute than xmorph since it 
has been actively developed in last years.

<h2> tkmorph </h2>

tkmorph runs under many window systems, including the X Window System,
Microsoft Windows, and Macintosh.  Tkmorph requires the use of TCL, the
Tool Command Language written by John Ousterhout and others, the widget
Toolkit (Tk) that accompanies TCL, and the TCL/Tk shell called "wish"
with the "load" command enabled, which allows dynamic loading of
modules.  When you build "tkmorph" you are actually building dynamic
shared libraries to be loaded into an existing executable program, the
"wish" shell.  The actual "tkmorph" program is a TCL script.

You can obtain TCL and Tk for free from
  http://sunscript.sun.com/

You will also need some TCL scripts from Donald K. Fellows:
  http://r8h.cs.man.ac.uk:8000/tcl/
You will need dirbrowser3 and all of the routines needed by
dirbrowser3, which are inside dkflib, the "Generic Useful Library".

tkmorph has not been developed in latest years and may be unusable nowadays.

<h2> morph </h2>

morph runs with no graphics display and is very portable.  It is
intended to be used alonside the other programs.  Morph can perform
image warping and dissolving, using meshes generated by Xmorph or
Tkmorph or gtkmorph.


<h1> ON MORPHING </h1>

Morphing was invented and first used by Industrial Light and Magic.
The original author of the first morphing algorithm is Douglas B.
Smythe.  If you can get ahold of the article, read Douglas B.  Smythe's
article ``A Two-Pass Mesh Warping Algorithm for Object Transformation
and Image Interpolation'', ILM Technical Memo 1030, Computer Graphics
Department, Lucasfilm Ltd., 1990.  This kind of morphing is technically
nothing more than a simultaneous warp and dissolve of an image.
Another kind of morphing, which is far more involved than what xmorph
does, uses 3D models of the two things being morphed.

The first commercial use of morphing was in a sequence in the movie
<em> Willow</em>.  Since then, morphing has been widely used.  Among the
more memorable morphing sequences are those found in Michael
Jackson's ``Black or White'' video, and in the movie <em> Terminator 2</em>.

Be sure to read George Wolberg's <em> Digital Image Warping</em>.  I have
corresponded with George Wolberg about this program.  I asked him
whether he considered xmorph to be a violation of copyright of the
algorithms in his book, since there are similarities.  Mr. Wolberg
assured me that my algorithms were different enough that there was no
problem, and he seemed very interested and enthused about the existence
of my public domain implementation.  Also, the algorithms published in
Mr. Wolberg's book had bugs in them which I and other xmorph
contributors have found, and those bugs have been reported to George
Wolberg, who verified my corrections to be proper.  I was also told
that these bugs were propagated on to Lucasfilm, although I have heard
from no one at Lucasfilm directly.


<h1>THE NEW PROJECT </h1>

In sep 2000, when the gtkmorph code was added to this project,
the xmorph project was completely reorganized
to use the autoconf/automake programs by GNU.

The source code was divided into subdirectories, as follows

<pre>
/          <-  base autoconf stuff, and  README and etc
/po        <-  NLS (gettext) translation stuff
/intl      <-  gettext (for sites where it is not available)
/doc       <-  documentation
/libmorph  <-  the morphing code (the LIB_OBJS in the old project)
/xmorph    <-  the Athena code (the GUI_OBJS in the old project)
/gtkmorph  <-  the GTK code
/tkmorph   <-  the TK code
/example   <-  example morphing projects
</pre>

The configuration of the project is now done thru two channels:
the "configure" script , and the "Makefile.conf" file.


<h1>INSTALLATION</h1>

<h2> source code </h2>

xmorph, tkmorph, and morph are written in ANSI C.  Tkmorph also has its
graphical user interface and other operational code written in TCL.
Tkmorph uses SWIG, the Simplified Wrapper Interface Generator, to
create most of the TCL wrapper code. <br>

gtkmorph is not strictly ANSI, you may need the gcc compiler
to compile it; moreover some parts are in C++. gtkmorph needs to link
to external libraries, namely:
the GTK libraries;
the Waili wavelet library (used for "wavelet equalization").

<h2> configuring </h2>

You may disable/enable  features using the "configure" script;
"configure" will generate a Makefile to build the project.
You may not edit the file Makefile: it is automatically generated.
Type  "sh configure --help" to know about available options.

Please refer to the file INSTALL for further instructions.

<h2>troubleshooting</h2>

The following tips were written for the old project: 
if you have problems, you better read them.

<pre>
> GETTING HELP WITH COMPILING
> 
> If you have problems getting xmorph to compile, link, or run
> correctly, please do the following before asking me for help:
> 
> () Make sure you have the latest version of this program.
> 
> () If you do not know how to compile programs, then I assume that if
> you are taking on this task, you want to understand how the process
> works.  In that case, be willing to teach yourself how to use a
> computer the way most programmers do:  Read the man pages and use a lot
> of trial and error.  The process seems tedious and slow at first, but
> you will eventually find that most bugs are not serious, and that you
> can fix them yourself.
> 
> () Pay close attention to the error the computer gives you.  Is the
> error from the make program, the C preprocessor, the C compiler, or the
> linker?  Is the link dynamic or static?  If you feel ready to report a
> compile error, make sure, for example, that the error is in fact a
> compiler error, and not a linker error.  The error could also be a
> preprocessor error, such as when the header files you need can not be
> found.
> 
> () Carefully read the man page for your 'make' utility to see whether
> it operates in a nonstandard way.  If so, then you will either need
> another make program, or you will have to find the '-' option which
> forces your make program to behave properly.
> 
> () If the error is a preprocessor error, such as a complaint that
> header files could not be found, find out why the header files could
> not be found.  Perhaps on your machine, the header files are in a
> nonstandard place.  This is true for Solaris, for example.  Ask your
> system administrator for help finding them.
> 
> () Carefully read the man page and whatever other documentation you
> have for your compiler to see what the error the compiler gave you
> means.  Compiler errors are not as mysterious as people would like to
> pretend they are.
> 
> () Carefully read the man page for your static linker and your dynamic
> linker.  Know whether you are linking dynamic libraries or static
> libraries.  Most systems, sadly, do not have the same libraries for
> static and dynamic linking, so if one set does not work, try the
> other.  This fixes most linker problems I have seen so far,
> particularly on SunOS or Solaris, and FreeBSD.
> 
> () Ask your system administrator to help you.  Most of the so-called
> bug reports I receive have to do with the details of the machine the
> person is compiling on, and I can provide no insight into their
> problem.  The system administrator exists for a reason, which is to
> centralize knowledge about how your computers operate.
> 
> Occasionally I will make a new release of this program which has a bug,
> but most long-lasting releases have no known bugs, and the problems
> that are reported to me are in those cases always eventually solved by
> the user asking their system administrator for information, and the
> information is invariably something I could not know about because it
> is specific to your machine.  About a third of problems reported to me
> could have been handled without my help if the person read the Makefile
> comments.
> 
> 
> 
> 
> SUCCESS BUILDING XMORPH ON SPECIFIC SYSTEMS
> 
> This program has been tested on various models of Sun SPARCs running
> both SunOS and Solaris, SGI's running IRIX, Intel running Linux, Intel
> running MS Win95 and MS WinNT, DEC Alpha running Digital UNIX, and
> various HP machines running HPUX.  The code is so portable that no
> modifications are necessary to compile on these machines, except for
> those documented in the Makefile.  Of course, operating systems change,
> and new bugs are written, so if you find that the status of xmorph's
> portability has changed, then please let me know so that it can be
> fixed.  If you get Xmorph running on other architectures, please send
> email to me to report your success, and whether you had any problems
> compiling, and what the solutions were to those problem.
> 
</pre>


<h1>REPORTING BUGS</h2>

Send bug reports to mennucc1@debian.org, or report them
at <a href="http://sf.net/projects/xmorph">the project page</a>.

<ul>
<li> Reports that are related to the GIMP plugin version of xmorph should
be cc'ed to Gordon Matzigkeit <gord@gnu.org>. 
(Unfortunately the gimp plugin is now broken).

<li> Tell me the version of xmorph or tkmorph you are using.  The version
is the same as the distribution date, such as "1999jul16".

<li> If you are using tkmorph then tell me what version of the "wish" shell
you are using.  This information is available by issuing these
commands:
    <pre>    puts $tcl_version $tk_version </pre>

<li> Include details about the type of error encountered, and at what
stage it happened.  (i.e., make, preprocessor, compiler, linker,
execution, etc.)

<li> Tell me the operating system and version you are using, as well as
which variety of the X Window System you are using (for example, Open
Group or OpenWindows or XFree86 or whatever).  Also tell me what
version you are using (X11R6.3 or whatever).  If you are using MS Win95
or MS WinNT then tell me so.

<li> Tell me the configuration of the display hardware and software on the
machine that xmorph or tkmorph failed on.  The output of "xdpyinfo"
might be helpful in some cases for machines running X Window System.
The sort of information that would be useful are the number of bits per
pixel of your display (also called the "depth" of your display).  If
you are using MS Windows then the display information is available from
the "Control Panel / Display" utility.  Note that just because your
hardware might support a certain display depth, that does not mean your
X server is currently configured to use it.  In fact, as incredible as
it seems, high end Silicon Graphics workstations with 32-bit graphics
capabilities, including the Onyx with a Reality Engine, by default
configure their X servers to use 8 bit pseudo-color even though they
can support 24-bit true color.  This makes absolutely no sense at all,
of course, but there it is.

<li> Tell me everything I need to know to reproduce the error.

<li> If you followed instructions, you've completely read the Makefile and
the README file, in which case you know the magic word.  If you
include the magic word in your email message to me, the message will
automatically be given priority by my mail reader and I will find it
sooner.

</ul>

<h1>TODO</h1>

The GIMP plugin is broken.

<h1>RUNNING XMORPH or TKMORPH</h1>

There is a short xmorph man page, which tells you some nice things
about how to start xmorph, but most of the information about how to
actually use xmorph is contained within xmorph itself. <br>

Xmorph is self-documented, so run the program to find out how to
use it.  The internal documentation is coded in "help_menu.c".
Read all of the help menu information.  The best way to learn how to
use xmorph is to play with it after you read the help menus.<br>

The general sequence of events in using xmorph is this:

<ul>
<li>Find two images that you want to morph into each other.  The first
image is called the "source" image.  The second image is called the
"destination" image.  The resulting warp and dissolve between those two
images is called the "tween" image.

<li>Get these images into a computer.  You need to use some sort of
digitizing device, such as a flatbed scanner, or a video capture
device.  If you just want to play around at first to become acquainted
with xmorph, then you can find some images already in a computer
format.  There are zillions of images on the internet.  Check, for
example, ftp://wuarchive.wustle.edu.

<li>Make sure the images are both the same size and shape, in number of
pixels.  If the images did not start out being the same size, there are
many image manipulation programs, both free and commercial, which can
resize and crop (cut) images.  For example, PBMplus, netpbm,
ImageMagick, xv, and Photoshop all perform this sort of manipulation.

<li>Convert the images into the Targa image file format.  xmorph and
tkmorph read and write images in the Targa TrueVision (TGA) image file
format.  Targa has several methods of storing image data.  For best
results, use 24-bit or 32-bit full color.  The 24-bit format should
work for most situations.  The 32-bit format includes an "alpha"
transparency plane.  If you do not already know what an "alpha" plane
is, then it is beyond the scope of my intention to explain it here.
Suffice it to say that alpha is used to overlay (matte) one image on
top of another.

<li>  NOTE:  Xv and xmorph/tkmorph did not always share a common idea of
  what is a valid "Targa" image file.  I do not know why.  If you have
  trouble using Xv to view TGA images produced by xmorph, then you
  should either get a new version of Xv, or use another program to view
  your TGA images.  Later versions of Xv do not have this
  incompatibility, so I assume that the problem was a bug in Xv which
  has since been fixed.

<li> Run xmorph or tkmorph.  For more details, read the help menus within
xmorph or tkmorph.

<li>From within xmorph or tkmorph, read the two images.  The images will
appear behind meshes in the respective image panels.

<li>From within xmorph or tkmorph, manipulate the meshes by dragging mesh
points around.

<li>From within xmorph, perform a "morph sequence".  This involves
selecting a the number of in-between images to create, and the file
name of the images.  Xmorph will warp and dissolve the images, and
write them to image files.
</ul>


<h1>RUNNING THE XMORPH GIMP PLUG-IN</h1>

The GIMP (GNU Image Manipulation Program, see http://www.gimp.org/) is
a powerful Adobe Photoshop look-alike for Unix systems.  Its plug-in
interface allows external programs to manipulate GIMP images directly.
If you have installed the GIMP, and compile xmorph with GIMP support
(search for the word `GIMP' in the xmorph Makefile), the resulting
binary can be used both as a standalone application and as a GIMP
plugin.

See the above section for information about running xmorph directly.
To run xmorph as a GIMP plugin, just create a symbolic link from the
xmorph binary to your GIMP plugin directory.

If you are not the superuser, that command will be something like:
  ln -s /usr/local/bin/xmorph ~/.gimp/plug-ins/xmorph

If you are the superuser, and you want to add morphing capabilities to
every GIMP user on the system, do something like:
  ln -s /usr/local/bin/xmorph /usr/local/lib/gimp/0.99.15/plug-ins/xmorph

Then, restart the GIMP application.  There should now be a menu entry,
Image/Filters/Effects/Morph, that you can use to do morphing.  Open
a new source RGB or grayscale image, click the right mouse button and
select Filters/Effects/Morph.  This starts the xmorph plugin, which
resembles the main application, except you cannot load images from
files.

Select the destination GIMP image via the Destination menu, and be
sure to set the sequence number of steps to a reasonable number (each
step generates a new GIMP layer).  You can run Morph Sequence/Preview
Warp Sequence to view the morph without exporting it to the GIMP.

When you are satisfied with the morph, run Morph Sequence/Warp
Sequence.  This will write the morph frames to new layers on top of
the source image.  The standard procedure is then to convert the image
to an indexed image, then save the layers as an animated GIF.

Caveat: the scripting interface to xmorph has not been well-tested
because I'm not very familiar with script-fu.


<h1>CREATING MOTION ANIMATIONS (i.e. MAKING MOVIES FROM IMAGES)</h1>

This section covers this topic: how to make an animation of the progressive
morphing between two images.<br>

This section does not cover this topic: how to morph two different movies
to build a third movie (in which some parts are dynamically moving and
morphing, as you see in SF in movies); this is theoretically possible,
but it would be very hard.


<h2> gtkmorph</h2>
gtkmorph can build an animation, with different output formats
 formats
<ul><li> gif animations (using 
the tool <em>convert</em> command from the package <em>ImageMagick</em>),
<li> mpeg format 
  (using <em>mpeg_encode</em> from the tool set <em>ucbmpeg</em>),
<li>or in MPEG4/DIVX format, using <em>mencoder</em>.
</ul> 
The above tools are not part of the xmorph package, and must be installed
separately.
Use the function <em>morph sequence<em> from the menu <em>morph</em>
to make animations.

<h2> xmorph</h2>
See the "xmorph.man" man page for some info about how to make movies
out of a sequence of images.<br>

Some other systems have commercial tools for generating animations
from a sequence of image files:

<ul>
<li>
  Adobe Premier can import a sequence of Targa files (and other
  sequences) to create a motion video, such as a Quicktime or AVI
  (audio-video interleaved) movie.

<li>
  Silicon Graphics IRIX has tools such as mediaconvert and dmconvert
  to create movies from images, including Targa files.

<ul>
    Here is an example of how to use dmconvert:
<li>
    (0) Let us say that you have a sequence of 30 Targa images named
        'warp0000' to 'warp0029' that you want to make into a movie.
<li>
    (1) Enter the command
          dmconvert -D -n warp####.tga warp####.tga
        to make sure that the image files can be read by dmconvert.
        You should get a list of information about the image files.
<li>
    (2) Enter the command
          dmconvert -f sgimv -n warp####.tga -p video warp####.tga out.movie
        This should create an SGI movie from the images warp0000,
        warp0001, ..., warp0029.  To play the movie, type movieplayer
        out.movie.
</ul>
Also see Andy Thaler's WWW home page (the URL is given elsewhere in
this file) for links to some relevant programs.
</ul>


<h1>RUNNING GTKMORPH</h1>

Run it , and start the guide from the help menu.


<h1>ABOUT TARGA IMAGE FILE FORMAT</h1>

I [Gourlay] have been asked by many people what image file format xmorph uses.
Xmorph uses the Targa image file format, also called TGA. <br>

Several people say that they can not find a program that supports Targa
image files, or ask what the Targa image file format is.  Here are
some answers:  <br>

TrueVision is a company that makes motion video hardware.  Some of
their hardware products are called "Targa something" where the
"something" part depends on the particular model.  The Targa TGA image
file format has been around for a long time and is still used (or at
least supported) by other software packages that handle digital video
editing and compression/decompression.  See the section in this README
about making movies from a sequence of image files.  <br>

TGA works well because it is sufficiently flexible to use a number of
storage schemes (including colormapped, 24-bit true color, 32-bit alpha
true-color, and gray scale) and it provides for some compression using
a form of run-length encoding which is modified to minimize the
worst-case expansion. <br>

Right now, Xmorph and tkmorph only read and write Targa image files.
There is a PBMplus (and netpbm) utility to convert Targa image files to
and from other formats.  Also, Art Department Pro's Professional
Conversion Pack (which runs on Amiga systems) has a Targa reader and
writer.  Targa files are also viewable from Image Magick utilities, but
they have to have a .tga extension to them for some reason (probably
because Targa files do not have a magic number in their header
identifying them as Targas.)  Adobe Premier can easily read a sequence
of TGA files and turn them into a full motion video clip. <br>

Gtkmorph reads images in almost any kind of format, and writes
them as .ppm (and other formats if the GTK library has version >= 2.2).