>K  + Z D ImageMagick - Image Processing and Display Package9VL

 
F
"I swear by my life and my love of it that I will neverKlive for the sake of another man, nor ask another man to live for mine"M

John Galt in Atlas Shrugged, by Ayn Rand


 

>Contents


>Author

The author isImagick@wizards.dupont.com.HThis software is NOT shareware. However, I am interested in who might beIusing it. Please consider sending me a picture postcard of the area where you live. Send postcards to
/
      John Cristy*      P.O. Box 409      Landenberg, PA  19350(      USA

FI'm also interested in receiving coins or stamps from around the worldfor my collection.

/Back to Contents

>Availability

ImageMagick, version 5.2.0, is available on ftp.wizards.dupont.com.ImageMagick clientOexecutables!are available for some platforms.IMacintosh,ANT,CVMS,andFLinux,source and binaries are also available.
K


I want ImageMagick to be of high quality, so if you encounterHa problem I will investigate. However, be sure you are using the mostrecent version fromSftp.wizards.dupont.com,Gor a mirror site, before submitting any bug reports or suggestions.bReport any problems via the web-basedreporting facility.

/Back to Contents
 

>WWW

.The official ImageMagick WWW page is at`www.wizards.dupont.com.

GTo use display as your external imageIviewer, edit the global mailcap file or your personal mailcap file.mailcap9(located in your home directory) and put this entry:
=
      image/*; display %s

3
Back to Contents
 


>Mailing"List


=There is a mailing list for discussions and bug reports aboutImageMagick."To subscribe send the message
:
      subscribe magick
toOmajordomo@wizards.dupont.com.GYou will receive a welcome message which tells you how to post messages to the listNmagick@wizards.dupont.com.
/Back to Contents
 

>Memory*Requirements

GYou should allocate sufficient swap space on your system before runningGImageMagick; otherwise, you may experience random server or applicationIcrashes. Anything less than 80 megabytes of swap space is likely to causerandom crashes.

HOn many systems, you will find that 80 megabytes is insufficient and youGwill have to allocate more swap space. You should also have at least 32Kmegabytes of real memory although 64 megabytes or more is recommended.

/Back to Contents
 

>UNIX)Compilation

Type:
Q
      gzip -dc ImageMagick-5.2.0.tar.gz | tar xvf -9      cd ImageMagick-5.2.0

If you do not have gunzip, it is available on prep.ai.mit.edu.

 

 

FUse configure to automatically configure, build, and install .ImageMagick.B

If you are willing to accept configure's default options, type:5

      ./configure
Hand watch the configure script output to verify that it finds everythingFthat you think it should. If it does not, then adjust your environmentso that it does.H

If you are not happy with configure's choice of compiler, compilationGflags, or libraries, you can give configure initial values forGvariables by setting them in the environment. Using a Bourne-compatible5shell, you can do that on the command line like this:H

    CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
IOr on systems that have the env program, you can do it like thisV
    env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
3The configure variables you should be aware of are:
        CC          Name of C compiler (e.g. 'cc -Xa') to use~        CFLAGS      Compiler flags (e.g. '-g -O2') to compile withy        CPPFLAGS    Include paths (-I/somedir) to look for header files{        LDFLAGS     Library paths (-L/somedir) to look for libraries                    Systems that support the notion of a library                    run-path may additionally require -R/somedir or                    '-rpath /somedir' in order to find shared libraries                    at run time.        LIBS        Extra libraries (-lsomelib) required to link
GAny variable (e.g. CPPFLAGS or LDFLAGS) which requires a directory path:must specify an absolute path rather than a relative path.H

By default, make install will install the package's files in/usr/local/bin,/usr/local/man,Jetc. You can specify an installation prefix other than /usr/local6by giving configure the option --prefix=PATH.L

Configure can usually find the X include and library files automatically,Nbut if it doesn't, you can use the configure options --x-includes=DIR:and --x-libraries=DIR to specify their locations.J

The configure script provides a number of ImageMagick specific options.OWhen disabling an option --disable-something is equivalent to specifying--enable-something=noKand --without-something is equivalent to --with-something=no.-The configure options are as follows (executeconfigure --helpto see all options).x

      --enable-shared      build shared libraries (default is no)t      --enable-static      build static libraries (default is yes)~      --enable-lzw         enable LZW support (default is no)X      --enable-16bit-pixel enable 16 bit pixels (default is no)z      --enable-socks       enable use of SOCKS 5 library and 'rftp'      --with-perl          enable build/install of PerlMagick (default is yes)y      --with-bzlib         enable BZlib (default is yes)      --with-dps           enable Display Postscript (default is yes)      --with-fpx           enable FlashPIX (default is yes)      --with-hdf           enable HDF (default is yes)}      --with-jbig          enable JBIG (default is yes)}      --with-jpeg          enable JPEG (default is yes)      --with-png           enable PNG (default is yes)}      --with-tiff          enable TIFF (default is yes)      --with-ttf           enable TrueType (default is yes)}      --with-zlib          enable Zlib (default is yes)      --with-x             use the X Window System
GImageMagick options represent either features to be enabled or packagesWto be included in the build. When a feature is enabled (via --enable-something),"it enables code already present in%ImageMagick. When a package isGenabled (via --with-something), the configure script will searchKfor it, and if is is properly installed and ready to use (headers and builtFlibraries are found by compiler) it will be included in the build. TheIconfigure script is delivered with all features disabled and all packagesIenabled. In general, the only reason to disable a package is if a packageGexists but it is unsuitable for the build (perhaps an old versionor not+compiled with the right compilation flags).2

Several configure options require special note:

Building under Cygwin:J

ImageMagick may be built under the Windows NT/'9X Cygwin Unix-emulation(environment which may be downloaded from:Cygnus.<Pre-compiled X11R6.4 libraries for Cygwin are available fromJNASA.GUse the same procedure as for Unix except that building DLLs is not yetIsupported so do not specify --enable-shared option to configure..

Dealing with configuration failures:F

While configure is designed to ease installation of ImageMagick, itGoften discovers problems that would otherwise be encountered later whenKcompiling ImageMagick. The configure script tests for headers and librariesMby executing the compiler (CC) with the specified compilation flags (CFLAGS),Fpre-processor flags (CPPFLAGS), and linker flags (LDFLAGS). Any errorsJare logged to the file config.log. If configure fails to discoverJa header or library please review this log file to determine why, however,Lplease be aware that *errors in the config.log are normal* because configureQworks by trying something and seeing if it fails. An error in config.logGis only a problem if the test should have worked on your system.. AfterJtaking corrective action, be sure to remove the config.cache fileJbefore running configure so that configure will re-inspect the environment rather than using cached values.F

Common causes of configure falures are: 1) a delegate header is notFin the header include path (CPPFLAGS -I option); 2) a delegate libraryJis not in the linker search/run path (LDFLAGS -L/-R option); 3) a delegateHlibrary is missing a function (old version?); 4) compilation environment is faulty.G

If all reasonable corrective actions have been tried and the problemFappears to be due to a flaw in the configure script, please send a bug4report to the configure script maintainer (currentlyPbfriesen@simple.dallas.tx.us).HAll bug reports should contain the operating system type (as reported byMuname -a) and the compiler/compiler-version. A copy of the configureJscript output and/or the config.log file may be valuable in orderHto find the problem. If you send a config.log, please also sendGa script of the configure output and a description of what you expectedGto see (and why) so the failure you are observing can be identified and resolved.
 
 

LTo confirm your build of the ImageMagick distribution was successful, type:
1
      display

FIf the program faults make sure that you may have inadvertingly linkedDto an older version of the libMagick library. In this case type
9
      cd ImageMagick/magick+      make install$      cd ..)      make
4If the image colors are not correct use this commandA
      display -visual default

FYou can find other example images in the images directory.
T


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


GAlso read the ImageMagick Frequently AskedIQuestions This is a required reading. Most of the questions I get via3electronic mail are answered in this document.

FPlace display X application defaultsinF/usr/lib/X11/app-defaults/Display. Use the appropriate name for`other clients (e.g. Animate, Montage, etc). To execute displayIfrom as a menu item of any window manager (olwm, mwm, twm, etc), use
3
    display logo:Untitled

/Back to Contents
 

>Delegates

GTo further enhance the capabilities of ImageMagick, you may want(to get these programs or libraries:
 
>Background)Texture

KImageMagick requires a background texture for the TILE formatIand for the -texture option of montage.BYou can use your own or get samples or get additional samples from4KPT.

 
>BZLIB

IImageMagick requires the BZLIB library to read or write Zipcompressed MIFF images.

 
>RALCGM

RImageMagick requires ralcgm to read Computer Graphic MetafileQimages (may not compile under linux). You also need Ghostscript (see below).

 "
>TransFig

OImageMagick requires fig2dev to read TransFig images.

 
>GET

FImageMagick requires GET to read images specified with aLWorld Wide Web (WWW) uniform resource locator (URL). Note: do not confuseHthis get program with SCCS get program. If you do not have a HTTPWserver, you can use xtp, available in the ImageMagick)distribution, for URL's whose protocol isFTP.

 
>FreeType

HImageMagick requires the FreeType software, version 1.1 or above,%to annotate with TrueType fonts.

  
>HDF

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

 
>HTML2PS

FImageMagick requires html2ps to read HyperText Markup#Language (html) documents.

 
>JBIG

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

 
>JPEG

HImageMagick requires the Independent JPEG Group's software-to read and write the JPEG image format.

Apply the]losslessIJPEG patch to Independent JPEG Group's source distribution to read(lossless jpeg-encoded DICOM images:
E

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

 
>MPEG

GImageMagick requires the MPEG encoder / decoder to read or write"the MPEG image format.

  
>PNG

IImageMagick requires the PNG library, version 1.0 or above,)to read the PNG image format.

 
>Postscript

TImageMagick requires GhostscriptGsoftware to read the PostScript or the Portable Document format.FIt is used to annotate an image when an X server is not available. SeeHthe FreeType library above for another means to annotate an image. Note,QGhostscript must support the ppmraw device (type gs -h to verify). If GhostscriptGis unavailable, the Display Postscript extension is used to rasterize aFPostscript document (assuming you define HasDPS). The DPS extension isGless robust than Ghostscript in that it will only rasterize one page ofa multi-page document.

 
>RA_PPM

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

 
>RAWTORLE

OImageMagick requires rawtorle from the Utah Raster ToolkitBto write the RLE image format (may not compile under linux)..

 
>SANE

LImageMagick requires scanimage to import images from a scanner device.

 
>TIFF

HImageMagick requires Sam Leffler's TIFF software toKread and write the TIFF image format. It in turn optionally requires!the JPEG and ZLIB libraries.

 
>WMF

LImageMagick requires wmftopng to read Windows Meta File images.

 
>X(Server

GImageMagick requires an X server for display and animate to workIproperly. This free X server is available for Windows and Macintosh.

 
>ZLIB

OImageMagick requires the ZLIB library to read or write PNG$or ZLIB compressed MIFF images.


3
Back to Contents
 


>How(to Compile
3

Back to Contents
 


>VMS)Compilation


HYou might want to check the values of certain program definitions beforeHcompiling. Verify the definitions in delegates.mgk to suit your$local requirements. Next, type:
?
      unzip ImageMagick-5.2.0.zip9      set default [.imagemagick]$      @makeH      set display/create/node=node_name::

>where node_name is the DECNET X server to contact.

Finally type:1
      display

FAlternatively, get a zipped distribution (with JPEG, PNG, TIFF,andmTTF) from ftp.wizards.dupont.com.

MThe VMS JPEG, PNG, TIFF, and TTF source libraries are availableBon axp.psl.ku.dk in [anonymous.decwindows.lib].

XThanks to pmoreau@cenaath.cena.dgac.frIfor supplying invaluable help as well as the VMS versions of the JPEG,-PNG, TIFF, and TTF libraries.

3
Back to Contents
 


>Windows>NT/95 Visual C++ 6.0 Compilation


pThe Visual C++ distribution targeted at Windows NT or Windows 95Adoes not provide any stock workspace (DSW) or project files (DSP)Dexcept for those included with third party libraries. Instead, thereEis a configure program that must be built and run that creates0an environment that meets your particular needs.@The issue with the Visual C++ working environement is that thereAare a fairly large number of mutually exclusive options that must5all be used in a coherent manner, or problems result.GThe Visual C++ system provides three different types of runtimesBthat must match across all application, library, and DLL code that>is built. Configure creates a set of build files that0are consistent for a specific runtime selection.*The three options for runtime support are: 1) Multi-threaded DLL runtimes% 2) Single-threaded library runtimes$ 3) Multi-threaded library runtimesBIn addition to these runtimes, the VisualMagick build environementFallows you to select the way the ImageMagick components will be built.The three options for this are:3 1) Everything as DLL's - using real X11 libraries: 2) Everything as DLL's - using stubbed out X11 librariesC 3) Everything as static libraries - always using stubbed out X11.AThis leads to five different possible build options, which shouldFcover almost any particular situation. The default binary distributionBis built using #1 from the first list and #1 from the second list.FThis results in an X11 compatible build using all DLL's for everything7and multi-threaded support (the only option for DLL's).DTo do a build for your requirements, simply go to the configure sub-Bdirectory under VisualMagick and open the configure.dsw workspace.2Set the build configuration to "Release" under the1 "Build..., Set Active Configuration..." menuDBuild and execute the configure program and follow the instructions.DYou should probably not change any of the defaults unless you have aspecific reason to do so.DAfter creating you build environment you can proceed to open the DSW8file that was generated and build everything from there.EIn the final DSW file you will find a project call "All". In order toEbuild everything in the distribution, select this project and make itDthe "active" project. Set the build configuration to the desired oneF(Debug, or Release) and do a "clean" followed by a "build". You shoulddo the build in a specific way:4 1) Make the "All" prkect the active project (Bold)F Right click on the All project and select "Set As Active Project" 2) Select "Build..., Clean" 3) Select "Build..., Build"< 4) Go get some coffee unless you have a very fast machine.@The "Clean" step is needed in order to make sure that all of the?target support libraries are updated with any patches needed to.get them to compile properly under Visual C++.CAll of the required files that are needed to run any of the commandFline tools will be found in the "bin" subdirectory of the VisualMagickBsubdirectory. This includes EXE, and DLL files. You should be able@to test the build directly from this directory without having toBmove anything to any of the global SYSTEM or SYSTEM32 areas in theoperating system installation.CNOTE: The two utilities "display" and "animate" will only be usableFwhen the real X11 libraries are included. The other build environmentsBuses the X11 stubs to supply non-functional stubs for the X-WindowBfunctionality. There is no support for a "static" build of the X11Fsupport because the build procedures for the X11 libraries do not seemto support this.-To view any image in a Microsoft window, type convert image.ext win:>Make sure gswin32 (Ghostscript) is in your execution path (see?Autoexec.bat), otherwise, you will be unable to convert or viewa Postscript document.EMake sure iexplore (Internet Explorer) is in your execution path (seeFAutoexec.bat), otherwise, you will be unable to browse the ImageMagickdocumentation.1The NT executables will work under Windows 95/98.
/Back to Contents
 

>Macintosh)Compilation

LThe MacintoshLMacintosh distribution contains MetroWerks Codewarrior Professional projectsNfor compilation. For those who do not have access to CodeWarrior, the binariesHfor the command line utilities are enclosed. I had to comment the inlineintrinsic functions in0math.h in order to compile. If you haveJa better solution, let me know. Display,*animate,andDimport currently do not work on theMacintosh.

"I'm looking for a volunteer to get)DisplayandCanimate to work on the Macintosh.GI also need a volunteer is needed to write a simple Mac program to callthe@libMagick routines and display an image in a window.

/Back to Contents
 

>Animation

LTo prevent color flashing on visuals that have colormaps, animate(1) createsMa single colormap from the image sequence. This can be rather time consuming.JYou can speed this operation up by reducing the colors in the image beforeyouanimate them. Use+mogrify to colorreduce the images:
T
      mogrify +map -colors 256 scenes/dna.[0-9]*
JAlternatively, you can use a Standard Colormap; or a static,direct,For true color visual. You can define a Standard ColormapQwith xstdcmap(1). For example, to use the "best" Standard Colormap,type:2
      xstdcmap -bestH      animate -map best scenes/dna.[0-9]*

#or to use a true color visual:
U
      animate -visual truecolor scenes/dna.[0-9]*

HImage filenames can appear in any order on the command line if the sceneKkeyword is specified in the MIFF image. Otherwise the images displayGin the order they appear on the command line. A scene is specified whenHconverting from another image format to MIFF by using the "scene"Ioption with any filter. Be sure to choose a scene number other than zero.KFor example, to convert a TIFF image to a MIFF image as scene#2, type:
P
      convert -scene 2 image.tiff image.miff

3
Back to Contents
 


>16-BIT%Imaging


GBy default, ImageMagick uses a color depth of 8 bits (e.g. [0..255] forHeach of red, green, blue, and transparency components). Any 16-bit imageFis scaled immediately to 8-bits before any image viewing or processingKoccurs. If you want to work directly with 16-bit images (e.g. [0..100535]),edit;Magick.tmpl and define QuantumLeap or use-enable-16bit with configure. Next, type:
"
    make clean    make
GIn 16-bit mode expect to use about 33% more memory on the average. AlsoJexpect some processing to be slower than in 8-bit mode (e.g. Oil Painting,Segment, etc).H

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

3
Back to Contents
 


>64-BIT&Machines


<Each pixel, within ImageMagick, is represented by thePixelPacketHstructure found in magick/image.h. Only 8 bits are required forFeach color component and 16 bits for the colormap index for a total ofG6 bytes. If QuantumLeap is defined (see 16-BIT IMAGING above),Fthe color component size increases to 16 bits for a total of 10 bytes.JSome 64-bit machines pad the structure which can cause a significant waste#of memory. For the cray, change the+PixelPacket structure to this
3
    typedef struct _PixelPacket    {,      unsigned char>        red : QuantumDepth,@        green : QuantumDepth,?        blue : QuantumDepth,B        opacity : QuantumDepth;-      unsigned short6        index : 16;'    } PixelPacket;
before compiling.G

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

3
Back to Contents
 


>MIFF*Image Format


IMIFF is an image format which I developed. I likeit because

    
  1. GIt is machine independent. It can be read on virtually any computer. No byte swapping is necessary.
  2. 
  3. KIt has a text header. Most image formats are coded in binary and you cannotHeasily tell attributes about the image. Use more(1) on MIFF image9files and the attributes are displayed in text form.
  4. 
  5. GIt can handle runlength-encoded images. Although most scanned images doGnot benefit from runlength-encoding, most computer-generated images do.KImages of mostly uniform colors have a high compression ratio and therefore(take up less memory and disk space.
  6. 
  7. GIt allows a scene number to be specified. This allows you to specify anFanimation sequence out-of-order on the command line. The correct order5is determined by the scene number of each image.
  8. 
  9. GMIFF computes a digital signature for images. This is useful forFcomparing images. If two image files have the same signature, they areidentical images.
  10. 
  11. FThere is a montage keyword allowing an image to act as a visual6image directory. See display(1) for more details.
  12. 

9One way to get an image into MIFF format is to use"convertFor read it from an X window using the importGprogram. Alternatively, type the necessary header information in a fileKwith a text editor. Next, dump the binary bytes into another file. Finally, type
_
      cat header binary_image | display -write image.miff -

GFor 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:
O
      id=ImageMagick columns=640 rows=480 :

GThe image file would have red, green, blue tuples (rgbrgbrgb...). Referto theEdisplay manual page for more details.

3
Back to Contents
 


>Copyright


1Copyright (C) 2000 ImageMagick Studio

HPermission is hereby granted, free of charge, to any person obtainingKa copy of this software and associated documentation files ("ImageMagick"),Hto deal in ImageMagick without restriction, including without limitationHthe rights to use, copy, modify, merge, publish, distribute, sublicense,Pand/or sell copies of ImageMagick, and to permit persons to whom the ImageMagickDis furnished to do so, subject to the following conditions:

JThe above copyright notice and this permission notice shall be included>in all copies or substantial portions of ImageMagick.

JThe software is provided "as is", without warranty of any kind, expressKor implied, including but not limited to the warranties of merchantability,Ffitness for a particular purpose and noninfringement.In no event shallGImageMagick Studio be liable for any claim, damages or other liability,Fwhether in an action of contract, tort or otherwise, arising from, outZof or in connection with ImageMagick or the use or other dealings in ImageMagick.

GExcept as contained in this notice, the name of the E. I. du Pont deLNemours and Company shall not be used in advertising or otherwise to promoteRthe sale, use or other dealings in ImageMagick without prior written authorization%from the ImageMagick Studio.



Home Page9Image manipulation software that works like magic.