xmorph: Digital Image Warp ("morph") graphical user interface

Written and Copyright (C) 1994, 1995, 1996 by Michael J. Gourlay

NO WARRANTEES, EXPRESS OR IMPLIED.

Xmorph is a digital image warping program, also known as a "morphing"
program.  It 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 MIT, and part of the typical X
installation.  It is written in ANSI C.

Xmorph loads, saves, warps, and dissolves images, and loads, saves,
creates, and manipulates control meshes which determine the warping.
Xmorph has help pages built into it, so no external documentation is
necessary.

---

FURTHER READING:

Morphing was invented and first used by Industrial Light and Magic.
The original author of the first morphing algorithym 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.

The first commercial use of morphing was in a sequence in the movie
_Willow_.  Since then, morphing has been wildely used.  Among the
more memorable morphing sequences are those found in Michael
Jackson's "Black or White" video, and in the movie _T2_.

Be sure to read George Wolberg's _Digital Image Warping_.  I've
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've
heard from no one at Lucasfilm directly.

----====####====----

DISTRIBUTION and WHERE TO GET NEW VERSIONS:

I've occasionally found xmorph being distributed without my consent
on CDROM's, (and on some CDROM's with my consent).  I generally have
no problem letting people distribute xmorph on CD, except that I want
to have a copy of the CD for myself.  Also, if I know about the CD, I
can tell people to buy it, so it's to our mutual advantage to let me
know about CD's with xmorph.

One company that distributes xmorph with my consent is Digital
Equipment Corporation.  They give out their Multimedia Showcase CDROM
for free to interested Digital UNIX Alpha users.  If you own a DEC
Alpha, I suppose that you cna ask DEC for this CDROM.

Beware that versions released on CD are more than likely not the
latest version, since CD's last forever but latest versions last for
about 8 months.

The place where I make official new releases of xmorph is at MIT with
the rest of the X Window System contributed software.  Look for
xmorph in ftp.x.org (was export.lcs.mit.edu) in the contrib directory
heirarchy, in the applications or graphics subdirectories.  This site
is mirrored around the world.  Please find the MIT mirror most
appropriate for you.  There are several mirrors in Europe, and from
what I'm told, if you're in Europe, network delays calling MIT
directly are very bad, so look for a mirror local to you.

NOTE:  Since the MIT X Window System FTP site changes its structure
each time they make a new major release of the X Window System, the
place where the latest xmorph can be found might change.  I make a new
release about twice a year, so if the version you find is much older
than about six months, then it's probably not the latest version.

I've also found that a Linux version is being maintained by someone
(make yourself knows to me!) and that version is kept at
sunsite.unc.edu along with other Linux software for X.

---

INSTALLATION:

Carefully read the Makefile for instructions on how to compile the
program.

---

GETTING HELP WITH COMPILING XMORPH:

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 don't know how to compile programs, then I assume that if
you're 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't
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'll 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've 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, IBMPC running Linux, DEC
Alpha running Digital UNIX, and an HP 9000 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 this status of xmorph's portability has changed, then plase 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.


---

REPORTING BUGS:

Send bug reports to michael.gourlay@colorado.edu.

* Tell me the version of xmorph you're using.

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

* Tell me the operating system and version you're using, as well as
which variety of the X Window System you're using (for example, MIT
or OpenWindows or XFree86 or whatever).

* Tell me everything I need to know to reproduce the error.

* 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'll find it
sooner.

---

RUNNING XMORPH:

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.

The general sequence of events in using xmorph is this:

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.

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 aquainted
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.

Make sure the images are both the same size and shape, in number of
pixels.  If the images didn't 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.

Convert the images into the Targa 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" tranparency
plane.  If you don't already know what an "alpha" plane is, then it's
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.

  NOTE:  Xv and xmorph do not share a common idea of what is a valid
  "Targa" image file.  I don't know why, yet.  For now, just don't use
  Xv to view Targa images generated by xmorph.

Run xmorph.  For more details, read the help menus within xmorph.

From within xmorph, load the two images.  The images will appear
behind meshes in the respective image panels.

From within xmorph, manipulate the meshes by dragging mesh points
around.

From within xmorph, perform a warp 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.

---

CREATING MOTION ANIMATIONS (i.e. MAKING MOVIES FROM IMAGES):

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

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

  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.

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

    Here is an example of how to use dmconvert:

    (0) Let's say that you have a sequence of 30 Targa images named
        'warp0000' to 'warp0029' that you want to make into a movie.

    (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.

    (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.

Also see Andy Thaler's WWW home page (the URL is given elsewhere in
this file) for links to some relavent programs.

---

DISPLAY HARDWARE NOTES:

Xmorph is designed to work on static gray 1-bit, pseudo-color 8-bit,
and true-color 24-bit displays.  If you are running on a static gray
or pseudo-color display, the images that show up in the xmorph image
panels are dithered (which makes them look grainy), but the images
stored internally are full-color non-dithered, and the image files
written by xmorph are full-color non-dithered.  Don't let the
relatively poor image quality of the dithered image panels concern
you.  They are only "schematic" images to let you manipulate the
meshes.  Remember that the xmorph graphical user interface is
primarily used to manipulate meshes, not to display images.  To view
your morphs in full glory requires that you make an animation of your
image sequence.

A note about color dithering:

I've made the color dithering routines somewhat generic, in the sense
that you can choose the number of bits per channel that you want to
use when creating the so-called "dithering colormap".  Look in
"diw_map.h".  You can change the number of bits used to represent
each of the channels red, green, and blue.  It's generally believed
that the human eye is moste sensative to green, and least sensative
to blue, so it makes sense to give more bits to green and fewer to
blue.  However, one could imagine that somebody could prefer to give
more bits to another color, or whatever you want.

Also, for 16-bit colormapped displays (which are becoming more common
now), you could conceivably use up 8 bits or more for your colormap
without worrying about interference with other programs.  It'd
recommend using a RGB-332 dithering colormap in that case.

Another thing:  Some monochrome displays simulate PseudoColor by
allowing the applications to have a colormap.  This makes application
programming more simple.  The X server then has the responsibility of
dithering from color to monochrome.  Some such monochrome systems
have a 4-bit PseudoColor simulation mode which could conceivably be
used with xmorph, if some changes were made in the dither_image
routine in "image_x.c".  The colormap situation is easy to deal with:
Just use 1 bit per channel to get an RGB-111 dithering colormap.

---

ABOUT TARGA IMAGE FILE FORMAT:

I've been asked by many people what image file format xmorph uses.
Xmorph uses the Targa image file format, also called TGA.

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

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 editting and compression/decomression.  See the section
in this README about making movies from a sequence of image files.

TGA works well because it's sufficiently flexible to use a number of
storage schemes (including colormapped, 24-bit true color, and 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.

Right now, Xmorph only reads and writes Targa image files.  There is
a PBMplus (and netpbm) utility to convert Targas to and from other
formats.  Also, Art Department Pro's Professional Conversion Pack
(which runs on Amiga systems) has a Targa loader and saver.  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 don't have a magic number in their header identifying them as
Targas.)


----====####====----

WORLD WIDE WEB SITES:

For xmorph animations see Andy Thaller's WWW home page at

http://www.informatik.tu-muenchen.de/cgi-bin/nph-gateway/hphalle2/~thaller

The old one was at this address:
http://www.informatik.tu-muenchen.de/cgi-bin/nph-gateway/hphalle8/~thaller


---

Please report to me if you have animations that are cool that you'd
like other people to see.

----====####====----

TO DO:

I think it would be really cool and very appropriate if I got "before"
and "after" pictures of Michael Jackson and morphed one into the other
as a test.  If anybody has such images, please send them to me.

--

I would like to port xmorph to other window systems.  I need to
abstract out the functionality from the window system even further.
That's sort of tough because most of this is highly interactive at a
level that's more intricate than pushing buttons.  But still, it can
be done.

It would be slick if this were ported to Tk, in which case xmorph
would run on other window systems sort of automatically.

As of summer 1996, I've begun to port xmorph to use TCL/Tk.  The new
program will be called "tkmorph".  Development is slow but steady.
If anybody wants to help test or write this, let me know.  I plan to
make the Tk version easier to use than the Xt version, and in all
likelihood, I will not develop the Xt version any further, except
where it's possible to share code between the Tk and the Xt
versions.  I have access to a Win96 machine, but not to a Macintosh
with a C compiler, so I can't test tkmorph on a Macintosh.  I'd
appreciate if someone helped me out with development on a Mac.

--

I want to change to change the user interface to a mode-based sort of
thing where only one mouse button is used to do everything.
There are 5 mesh manipulation functions:

  Pick up a mesh point and drag it to another place
  Add a horizontal mesh line
  Add a vertical mesh line
  Delete a horizontal mesh line
  Delete a vertical mesh line

What I would probably do is create a panel of mode buttons that
selected one of the above modes.  Then the cursor would reflect which
mode you were in.  That would elliminate the need to press and hold
the Shift key while using the mouse.  That's akward.  Also, as it is
now, you have to remember which mouse buttons do what.  With a
mode-driven interface, you'd be reminded by the mode buttons and the
cursor shape, as in many paint programs.

The current interface has one cool feature that would be lacking in
the mode-driven method:  All of the mesh manipulations are a bunch of
Actions, which can be re-mapped by the user to be associated with
different events.  In a mode-driven interface, re-mapping would not
be possible to the same extent.  But on the other hand, why would
someone want to remap mesh manipulation events?

I also intend to support a wider range of image file types, including
JPEG, PPM, and TIFF.

If anybody is interested in helping out on these things, please let me
know.
