NAME xmorph/morph: image warpping and dissolving (morphing) programs AUTHOR Written and Copyright (C) 1994-1999 by Michael J. Gourlay This file is part of Xmorph. Xmorph 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. Xmorph 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. You should have received a copy of the GNU General Public License along with Xmorph; see the file LICENSE. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. DESCRIPTION Xmorph and tkmorph are digital image warping programs, also known as "morphing" programs. Xmorph and tkmorph 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. 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. 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". Morph runs with no graphics display and is very portable. It is intended to be used along with Xmorph or Tkmorph. Morph can perform image warping and dissolving, using meshes generated by Xmorph or Tkmorph. 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. SEE ALSO 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}. 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 T2}. Be sure to read George Wolberg's {\em Digital Image Warping}. 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. DISTRIBUTION I have 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 is to our mutual advantage to let me know about CD's with xmorph. Digital Equipment Corporation gives out their Multimedia Showcase CDROM for free to interested Digital UNIX Alpha users. If you own a DEC Alpha, I suppose that you can ask DEC for this CDROM. SGI distributes Xmorph on their Freeware CDROM and web site. If you have an SGI, look at http://freeware.sgi.com/ A major computer manufacturer distributes a very old (1996) verison of Xmorph with their machines which is broken, buggy, and lacks several important features (such as the ability to use 24-bit displays). If you have been using the version that comes with some machines, then you might be wasting your time with crippled code, and my credibility of a programmer has been diminished. This is the sort of problem I want to avoid by having people who want to print CDROM's first consult with me to make sure they have the latest version or that they notify their users or customers about how to obtain new versions from me. Beware that versions released on CD are more than likely not the latest version, since CD's last forever but latest versions last for a few months. The place where I make official new releases of xmorph is at my web site and sometimes at the Open Group X11 FTP site 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 hierarchy, in the applications or graphics subdirectories: ftp://ftp.x.org/contrib/applications ftp://ftp.x.org/contrib/graphics The Open Group site is mirrored around the world. Please find the Open Group mirror most appropriate for you. There are several mirrors in Europe, and from what I am told, if you are in Europe, network delays calling Open Group directly are very bad, so look for a mirror local to you. NOTE: Since the 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 is probably not the latest version. A Linux version is being maintained and that version is kept at sunsite.unc.edu along with other Linux software for X, but their version is ancient. A direct source of the source code is through my home page. I put releases up at this location more often than anywhere else: http://www.colorado-research.com/~gourlay/ http://www.colorado-research.com/~gourlay/software/ http://www.colorado-research.com/~gourlay/software/Graphics/ http://www.colorado-research.com/~gourlay/software/Graphics/Xmorph/ INSTALLATION Carefully read the Makefile for instructions on how to compile the program. 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. REPORTING BUGS Send bug reports to <gourlay@colorado-research.com>. * Reports that are related to the GIMP plugin version of xmorph should be cc'ed to Gordon Matzigkeit <gord@gnu.org>. * Tell me the version of xmorph or tkmorph you are using. The version is the same as the distribution date, such as "1999jul16". * 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: puts $tcl_version $tk_version * 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 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. * 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. * 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 will find it sooner. RUNNING XMORPH or TKMORPH 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. 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. The resulting warp and dissolve between those two images is called the "tween" 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 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. 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. 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. 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. Run xmorph or tkmorph. For more details, read the help menus within xmorph or tkmorph. From within xmorph or tkmorph, read the two images. The images will appear behind meshes in the respective image panels. From within xmorph or tkmorph, manipulate the meshes by dragging mesh points around. 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. RUNNING THE XMORPH GIMP PLUG-IN 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. 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 us 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 relevant 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. Do not 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. Notes about color dithering: I have made the color dithering routines within xmorph 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 is generally believed that the human eye is most sensitive to green, and least sensitive 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. I would 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. tkmorph uses Tk PhotoImages to display images and the dithering is a built-in function that I have relatively little control over. However, the Tk PhotoImage dithering seems to be fast and clean so I'm more than satisfied with it. In any case, the displayed image is dithered but the actual images that are written to output files are not dithered, as in xmorph. ABOUT TARGA IMAGE FILE FORMAT I have 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 not 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 editing and compression/decompression. See the section in this README about making movies from a sequence of image files. 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. 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. WORLD WIDE WEB SITES The main Xmorph web site is at http://www.colorado-research.com/~gourlay/software/Graphics/Xmorph/ That site has source code, example images, meshes and morph movies. 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 There is a weird morph on Bruno Boettcher's home page: http://erm6.u-strasbg.fr/~bboett/fr.index.html Please report to me if you have animations that are cool that you would 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 have access to a Win95 machine, but not to a Macintosh with a C compiler, so I can not test tkmorph on a Macintosh. I would appreciate if someone helped me out with development on a Mac. Enhance interpolation routines to handle situations where the mesh lines are not a true function (i.e. where a single abscissa has more than one ordinate.) This should be easy to fix either by parameterizing the spline or by using line segments for the interpolant. There is not really good reason not to use line segments for interpolants anyway -- they are easier and faster to compute and their behavior is more predictable than cubic splines. Line segments are less smooth but generally there will be so many knots that smoothing just gets in the way. Fix the problem where the last vertical line and the last horizontal line are black after a warp. This is probably a problem with the interpolation arrays. 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.
