> "I swear by my life and my love of it that I will never live for the sake of another man, nor ask another man to live for mine."

> John Galt in Atlas Shrugged, by Ayn Rand

## Contents

####

- Author
- Availability
- WWW
- Mailing List
- UNIX Compilation
- Extra Programs and Libraries
- How to Compile
- VMS Compilation
- NT Compilation
- Macintosh Compilation
- Animation
- 16-BIT Imaging
- 64-BIT Machines
- MIFF Image Format
- Copyright

##
Author

  The author is cristy@dupont.com. This software is NOT shareware. However, I am interested in who might be using it. Please consider sending me a picture postcard of the area where you live. Send postcards to

            John Cristy
            P.O. Box 40
            Landenberg, PA  19350
            USA

  I'm also interested in receiving coins from around the world.

Back to Contents

##
Availability

  ImageMagick, version 3.8.0, is available on ftp.wizards.dupont.com. ImageMagick client exectuables are available for some platforms. Macintosh, NT, and VMS source and binaries are also available.

  I want ImageMagick to be of high quality, so if you encounter a problem I will investigate. However, be sure you are using the most recent version from ftp.wizards.dupont.com, or a mirror site, before submitting any bug reports or suggestions.

Back to Contents

##
WWW

  The official ImageMagick WWW page is at www.wizards.dupont.com. Another useful ImageMagick WWW page is The Imaging Machine

  To use display as your external image viewer, edit the global mailcap file or your personal mailcap file .mailcap (located in your home directory) and put this entry:

            image/*; display %s

Back to Contents

##
Mailing List

  There is a mailing list for discussions and bug reports about ImageMagick. To subscribe send the message

            subscribe magick

  to majordomo@wizards.dupont.com. You will receive a welcome message which tells you how to post messages to the list magick@wizards.dupont.com.

Back to Contents

##
UNIX Compilation

  Type:

            gunzip ImageMagick-3.6.5.tar.gz
            tar xvf ImageMagick-3.6.5.tar
            cd ImageMagick

  You might want to check the values of certain program definitions before compiling. Change the definitions of ApplicationDefaults, BrowseCommand, EditorCommand, PostscriptColorDevice, PrintCommand, and RGBColorDatabase in `magick/magick.h` to suit your local requirements. Next, type.

            xmkmf
            make Makefiles
            make -k

  Note, ImageMagick requires an ANSI compiler. If the compile fails, first check to ensure your compile is ANSI compatible. If it fails for some other reason, try

            cd magick
            make -k
            cd ..
            make -k

  If you do not have gunzip(1), it is available on prep.ai.mit.edu. If you do not have xmkmf(1), or if xmkmf(1) fails to produce usable Makefiles, type

            configure
            make

  If you use `gcc` and get a link error, recompile with the option `-fPIC`. If you use `gcc` and get a core dump, recompile with the option `-fwritable-strings`. Dec Alpha users might need to remove `magick/XWDFile.h` and recompile to read images of type XWD. Change `ReadBinaryType` to `"r"` and `WriteBinaryType` to `"w"` in `magick/magick.h` for FreeBSD.

  Finally type:

            display images/aquarium.miff
            display -monochrome -dither images/aquarium.miff

  The aquarium and other images are available from anonymous FTP at ftp.x.org. If the image colors are not correct use this command

            display -visual default images/aquarium.miff

  You can find other example images in the images directory.

  For additional information, see the manual pages for these ImageMagick utilities

  display
  convert
  montage
  identify
  animate
  import
  mogrify
  combine

  Also read the ImageMagick Frequently Asked Questions This is a required reading. Most of the questions I get via electronic mail are answered in this document.

  Place display X application defaults in /usr/lib/X11/app-defaults/Display. Use the appropriate name for other clients (e.g. Animate, Montage, etc). To execute display from as a menu item of any window manager (olwm, mwm, twm, etc), use

          display logo:

  The ImageMagick utilities read and write MIFF images. Refer to the end of this message for more information about MIFF. Use convert to convert images to and from the MIFF format.

  ImageMagick utilities recognizes these image formats:

    AVS - AVS X image file.
    BMP - Microsoft Windows bitmap image file.
    CMYK - Raw cyan, magenta, yellow, and black bytes.
    EPS - Adobe Encapsulated PostScript file.
    EPSF - Adobe Encapsulated PostScript file.
    EPSI - Adobe Encapsulated PostScript Interchange format.
    FAX - Group 3.
    FITS - Flexible Image Transport System.
    GIF - CompuServe graphics interchange format; 8-bit color.
    GIF87 - CompuServe graphics interchange format; 8-bit color (version 87a).
    GRAY - Raw gray bytes.
    HDF - Hierarchical Data Format.
    HISTOGRAM
    JPEG - Joint Photographic Experts Group JFIF format; compressed 24-bit color.
    MAP - colormap intensities and indices.
    MATTE - Raw matte bytes.
    MIFF - Magick image file format.
    MTV -
    NULL - NULL image.
    PCD - Photo CD.
    PCX - ZSoft IBM PC Paintbrush file.
    PDF - Portable Document Format.
    PICT - Apple Macintosh QuickDraw/PICT file.
    PNG - Portable Network Graphics.
    PNM - Portable bitmap.
    PS - Adobe PostScript file.
    PS2 - Adobe Level II PostScript file.
    RAD - Radiance image file.
    RGB - Raw red, green, and blue bytes.
    RGBA - Raw red, green, blue, and matte bytes.
    RLA - RLA Alias/Wavefront image file; read only
    RLE - Utah Run length encoded image file; read only.
    SGI - Irix RGB image file.
    SUN - SUN Rasterfile.
    TEXT - raw text file; read only.
    TGA - Truevision Targa image file.
    TIFF - Tagged Image File Format.
    TILE - tile image with a texture.
    VICAR - read only.
    VID - Visual Image Directory.
    VIFF - Khoros Visualization image file.
    X - select image from X server screen.
    XC - constant image of X server color.
    XBM - X Windows system bitmap, black and white only.
    XPM - X Windows system pixmap file (color).
    XWD - X Windows system window dump file (color).
    YUV - CCIR 601 4:1:1 file.

  and for your convenience automatically converts most of these alien image format to MIFF at execution time. However, the MIFF image format has several advantages over most image formats (i.e. runlength encoding, visual image directories, digital signature on an image colormap, etc.). ImageMagick is designed to exploit these advantages. Whenever possible convert an alien image format to the MIFF format before using the various ImageMagick programs.

  Other formats may also be recognized. See convert for a list of valid image formats. You can specify a particular image format by prefixing the image filename with the image type and a colon (i.e. ps:image).

Back to Contents

##
Extra Programs and Libraries

  To further enhance the capabilities of ImageMagick, you may want to get these programs or libraries:

  ###
  X11 Stubs

    ImageMagick requires the X11 libraries. If your system does not have them, use this library instead. Display, animate, or import will not work with this library. The remaining programs have reduced functionality.

  ###
  Background Texture

    ImageMagick requires a background texture for the TILE format and for the -texture option of montage. You can use your own or get samples or get additional samples from KPT.

  ###
  RALCGM

    ImageMagick requires ralcgm to read Computer Graphic Metafile images (may not compile under linux).

  ###
  GET

    ImageMagick requires GET to read images specified with a World Wide Web (WWW) uniform resource locator (URL). Get(1) must be in /usr/local/bin. See WWWcommand in magick/image.h to change its location. Note: do not confuse this get program with SCCS get program. If you do not have a HTTP server, you can use xtp, available in the ImageMagick distribution, for URL's whose protocol is FTP.

  ###
  HDF

    ImageMagick requires the NCSA HDF library to read and write the HDF image format.

  ### JBIG

    ImageMagick requires the JBIG-Kit software to read and write the JBIG image format.

  ### JPEG

    ImageMagick requires the Independent JPEG Group's software to read and write the JPEG image format. ImageMagick creates progressive JPEG images by default. Use the `-interlace none` option to create non-progressive images , or undef C_PROGRESSIVE_SUPPORTED in jmorecfg.h before you compile the library, or use JPEG version 5B.

    Concerning iterative JPEG compression: see Kinoshita and Yamamuro, Journal of Imaging Science and Technology, Image Quality with Reiterative JPEG Compression, Volume 39, Number 4, July 1995, 306-312 who claim that (1) the iterative factor of the repetitive JPEG operation had no influence on image quality, and (2) the first compression determined base image quality.

  ###
  MPEG

    ImageMagick requires the MPEG library to read the MPEG image format. Use encoder encoder to write MPEG images.

  ###
  PICTTOPPM

    ImageMagick requires picttoppm to read Macintosh PICT images.

  ###
  Postscript

    ImageMagick requires GNU's Ghostscript software to read the PostScript or the Portable Document format. It is also required to annotate an image when an X server is not available. Note, Ghostscript must support the ppmraw device (type gs -h to verify). If Ghostscript is unavailable, the Display Postscript extension is used to rasterize a Postscript document (assuming you define HasDPS). The DPS extension is less robust than Ghostscript in that it will only rasterize one page of a multi-page document.

  ###
  PNG

    ImageMagick requires the PNG library to read the PNG image format. See Portable Network Graphics for more details.

  ###
  RA_PPM

    ImageMagick requires ra_ppm from Greg Ward's Radiance software to read the Radiance image format (may not compile under linux).

  ### RAWTORLE

    ImageMagick requires rawtorle from the Utah Raster Toolkit to write the RLE image format (may not compile under linux)..

  ###
  TIFF

    ImageMagick requires Sam Leffler's TIFF software to read and write the TIFF image format.

  ###
  ZLIB

    ImageMagick requires the ZLIB library to read the PNG image format or read or write ZLIB compressed MIFF images.

Back to Contents

##
How to Compile

  To display images in the HDF, JPEG, MPEG, PNG or TIFF format, get the HDF, JPEG, MPEG, PNG, TIFF, or XPM archives and build ImageMagick as follows:

  ###
  HDF

            cd ImageMagick
            gunzip -c HDF4.0r2.tar.gz | tar xvf -
            mv HDF4.0r2 hdf
            cd hdf
            configure
            make -k allnofortran
            cd ..

  ###
  JBIG

            cd ImageMagick
            gunzip -c jbigkit-0.9.tar.gz | tar xvof -
            mv jbig-kit jbig
            cd jbig
            make
            cd ..

  ###
  JPEG

            cd ImageMagick
            gunzip -c jpegsrc.v6a.tar.gz | tar xvof -
            mv jpeg-6a jpeg
            cd jpeg
            configure CC=cc -with-maxmem=7
            make
            cd ..

  ###
  MPEG

            cd ImageMagick
            mkdir mpeg
            cd mpeg
            gunzip -c mpeg_lib-1.1.tar.gz | tar xvof -
            mv mpeg_lib/* .
              edit Makefile as instructed; for Solaris use the
              BSD-compatibility libraries or replace bzero with a call to
              memset
            make
            cd ..

  ###
  PNG

            cd ImageMagick
            gunzip -c zlib-1.0.4.tar.gz | tar xvf -
            cd zlib
            make
            cd ..
            gunzip -c libpng-0.89c.tar.gz | tar xvf -
            mv libpng-0.88 png
            cd png
            make
            cd ..

  ###
  TIFF

            cd ImageMagick
            gunzip -c tiff-v3.4beta035.src.tar.Z | tar xvof -
            mv tiff-v3.4 tiff
            cd tiff
            configure
            make
            cd ..

  If your computer system supports shared libraries you must type

            make install

  Finally, perform the following:

            cd ImageMagick
            edit Magick.tmpl and define Has???? as instructed
            xmkmf
            make Makefiles
            make clean
            make

  If you do not have xmkmf, try

            configure
            make clean
            make -k

  If the compile fails due to a function redefinition it may be that either `jpeg/jconfig.h` or `mpeg/mpeg.h` is redefining `const`. Fix this problem and try again.
  You can now display images in the HDF, JBIG, JPEG, MPEG, PNG or TIFF format.

  If you have HDF, JBIG, JPEG, MPEG, PNG, and TIFF sources installed as directed above, you can also type

            Install sun

  Substitute the appropriate machine type (aix, hpux, sgi, etc).

Back to Contents

##
VMS Compilation

  You might want to check the values of certain program definitions before compiling. Change the definitions of ApplicationDefaults, DocumentationBrowser, EditorCommand, PostscriptColorDevice, PrintCommand, and RGBColorDatabase in `magick/magick.h` to suit your local requirements. Next, type.

  Type

            @make
            set display/create/node=node_name::

  where node_name is the DECNET X server to contact.

  Finally type:

            display [.images]aquarium.miff
            display -monochrome -dither [.images]aquarium.miff

  Alternatively, get a zipped distribution (with JPEG, MPEG, TIFF, and XPM) from ftp.x.org.

  The VMS JPEG, TIFF, and XPM source libraries are available on axp.psl.ku.dk in [anonymous.decwindows.lib].

  Thanks to pmoreau@cenaath.cena.dgac.fr for supplying invaluable help as well as the VMS versions of the JPEG, MPEG, TIFF, and XPM libraries.

Back to Contents

##
NT Compilation

  The NT distribution contains MetroWerks Codewarrior projects for compilation. For those who do not have access to CodeWarrior, the binaries for the command line utilities are included in the distribution.

  Set the path to the Ghostscript executable in `Autoexec.bat` if you want to recognize the Postscript format. If you have an NT X server like Exceed you will also need to include

          SET DISPLAY=:0.

  in `Autoexec.bat`.

  And yes, the NT executables will work under Windows 95.

Back to Contents

##
Macintosh Compilation

  The Macintosh distribution contains MetroWerks Codewarrior projects for compilation. For those who do not have access to CodeWarrior, the binaries for the command line utilities are included in the distribution. Display and animate currently do not work.

  I'm looking for a volunteer to get Display and animate to work on the Macintosh. I also need a volunteer is needed to write a simple Mac program to call the libMagick routines and display an image in a window.

Back to Contents

##
Animation

  An example animation sequence is available from ftp.x.org. Or alternatively, you can create this sequence yourself. Just look at README in the scenes directory.

  To prevent color flashing on visuals that have colormaps, animate(1) creates a single colormap from the image sequence. This can be rather time consuming. You can speed this operation up by reducing the colors in the image before you animate them. Use mogrify to color reduce the images:

            mogrify +map -colors 256 scenes/dna.[0-9]*

  Note, the image sequence in ImageMagick.animation.tar.gz is already reduced. Alternatively, you can use a Standard Colormap; or a static, direct, or true color visual. You can define a Standard Colormap with xstdcmap(1). For example, to use the "best" Standard Colormap, type:

            xstdcmap -best
            animate -map best scenes/dna.[0-9]*

  or to use a true color visual:

            animate -visual truecolor scenes/dna.[0-9]*

  Image filenames can appear in any order on the command line if the scene keyword is specified in the MIFF image. Otherwise the images display in the order they appear on the command line. A scene is specified when converting from another image format to MIFF by using the "scene" option with any filter. Be sure to choose a scene number other than zero. For example, to convert a TIFF image to a MIFF image as scene #2, type:

            convert -scene 2 image.tiff image.miff

Back to Contents

##
16-BIT Imaging

  By default, ImageMagick uses a color depth of 8 bits (e.g. [0..255] for each of red, green, blue, and transparency components). Any 16-bit image is scaled immediately to 8-bits before any image viewing or processing occurs. If you want to work directly with 16-bit images (e.g. [0..65535]), edit `Magick.tmpl` or `Makefile.in` and define `QuantumLeap` as instructed in the respective file. Next type

          make clean
          make

  In 16-bit mode expect to use about 33% more memory on the average. Also expect some processing to be slower than in 8-bit mode (e.g. Oil Painting, Segment, etc).

  In general, 16-bit mode is only useful if you have 16-bit images that you want to manipulate and save the transformed image back to a 16-bit image format (e.g. PNG, VIFF).

Back to Contents

##
64-BIT Machines

  Each pixel, within ImageMagick, is represented by the `RunlengthPacket` structure found in `magick/image.h`. Only 8 bits are required for each color component and 16 bits for the colormap index for a total of 6 bytes. If `QuantumLeap` is defined (see 16-BIT IMAGING above), the color component size increases to 16 bits for a total of 10 bytes. Some 64-bit machines pad the structure which can cause a significant waste of memory. For the cray, change the `RunlengthPacket` structure to this

          typedef struct _RunlengthPacket
          {
            unsigned char
              red : QuantumDepth,
              green : QuantumDepth,
              blue : QuantumDepth,
              length : QuantumDepth;

            unsigned short
              index : 16;
          } RunlengthPacket;

  before compiling.

  I'm not sure if this will work on other 64-bit machines that pad. If you know a better solution, please send me E-mail. Note, that the Dec Alpha apparently does not pad the structure so ImageMagick should be fine on this particular 64-bit machine.

Back to Contents

##
MIFF Image Format

  MIFF is an image format which I developed. I like it because

  1. It is machine independent. It can be read on virtually any computer. No byte swapping is necessary.

  2. It has a text header. Most image formats are coded in binary and you cannot easily tell attributes about the image. Use more(1) on MIFF image files and the attributes are displayed in text form.

  3. It can handle runlength-encoded images. Although most scanned images do not benefit from runlength-encoding, most computer-generated images do. Images of mostly uniform colors have a high compression ratio and therefore take up less memory and disk space.

  4. It allows a scene number to be specified. This allows you to specify an animation sequence out-of-order on the command line. The correct order is determined by the scene number of each image.

  5. MIFF computes a digital signature for images. This is useful for comparing images. If two image files have the same signature, they are identical images.

  6. There is a montage keyword allowing an image to act as a visual image directory. See display(1) for more details.

  One way to get an image into MIFF format is to use convert or read it from an X window using the import program. Alternatively, type the necessary header information in a file with a text editor. Next, dump the binary bytes into another file. Finally, type

            cat header binary_image | display -write image.miff -

  For example, suppose you have a raw red, green, blue image file on disk that is 640 by 480. The header file would look like this:

            id=ImageMagick columns=640 rows=480 :

  The image file would have red, green, blue tuples (rgbrgbrgb...). Refer to the display manual page for more details.

Back to Contents

##
Copyright

  Copyright 1997 E. I. du Pont de Nemours and Company Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of E. I. du Pont de Nemours and Company not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. E. I. du Pont de Nemours and Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

  E. I. du Pont de Nemours and Company disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall E. I. du Pont de Nemours and Company be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Image manipulation software that works like magic.