GraphicsMagick FAQ

GraphicsMagick FAQ

I received the following message, "?????? delegation failed ...". What does it mean?
How can I improve the appearance of 24-bit images displayed on my colormapped X server?
How do I set the transparency index in a GIF image so it displays properly within Mozilla?
How can I stop the filenames from changing in the title bar of the animate(1) image window?
The image grabbed by import(1) does not look like the image on my X server. What's wrong
How do I animate a digital YUV image sequence?
How do I view only the red channel of an RGB image?
How do I change the default PostScript page size?
When I display or convert an image, I get Memory allocation error. What can I do?
How do I concatenate three images left-to-right with no borders, frames, or text?
How do I create a GIF animation sequence to display within Netscape?
When I display a PostScript image it appears to be trimmed. I would like to display the entire page, including any white space.
What are visual image directories? How do I use them?
I have an HP. How do I take advantage of the Color Recovery option?
I use the window ID reported by xwininfo(1) with import and it does include the window manager frame as expected. How can I save the window with its frame?
I displayed an image and it appears as one solid color. What did I do wrong?
I received the following message, "???? library is not available ...". What does it mean?
I want to inspect the values of the matte channel within my image. How can I do that?
Convert in.gif out.png" says "Invalid Parameter - out.png"
How can I add one of those cool bevels to my image that I see used on the Web?
I try to launch display from my window manager and it fails. What's up?
When I convert Postscript to another format, how can I improve the appearance of the text?
How can I annotate an image with text that is 2 to 3 inches tall?
How can I convert my GIF animation sequence to individual image files?
How can I remove the background that prints around my image when I display it with Netscape?
How do I create a GIF or PNG image with Web safe colors?
How come Adobe Acrobat 2.1 can't read GraphicsMagick's PDF format?
How can I add a matte layer to my image?
How can I draw with text using 'convert' under Windows NT?
Why are my GIF files larger than expected?
Why are my JPEG files larger than expected?
How do I extract a single image from a multi-image file?

1. I received the following message, "?????? delegation failed ...". What does it mean?: GraphicsMagick uses several freely available packages to perform the translation of certain image formats (PostScript, MPEG, etc.). Make sure these packages are available as described in the README file. Also verify that you have plenty of temporary disk space. If not, set the TMPDIR environment variable to an area where space is available. Finally, for PostScript, verify that Ghostscript supports the pnmraw or ppmraw device (gs -h) and that the document contains valid PostScript statements (gs image.ps).
2. How can I improve the appearance of 24-bit images displayed on my colormapped X server?

If you have a colormapped X server, the number of unique colors in an image must first be reduced to match the requirements of your server before it can be displayed. Display tries to make the color reduced image closely resemble the original. However, there are some options that may improve the appearance.

You can use a private colormap. By default, your image must share colors with existing applications on your X server. The colors in your image may be very different than the shared colors and the results may be visually unsatisfactory. Try

 display -colormap private image.miff

The disadvantage is the annoying colormap loading and unloading as you move your pointer in and out of the image window.

The YCbCr colorspace may give better results when color reducing images of people faces. Try

 display -colorspace YCbCr image.miff

If you intend to view an image frequently, reduce the number of colors to match the resolution of your X server once and write to a new image. Then display this new image. For example,

 convert -colors 256 -dither image.jpeg image.miff
 display image.miff

This forces the time-consuming process of color reducing the image to one-time, rather than each time the image is displayed.

3. How do I set the transparency index in a GIF image so it displays properly within Mozilla?: Display your GIF image with display. Choose Matte from the Image Edit command menu and identify a pixel that has the transparency color. Press Method and select a matte edit method from a pop-up menu. Choose from these methods:

 point
 replace
 floodfill

The point method changes the matte value of any pixel selected with the pointer until the button is is released. The replace method changes the matte value of any pixel that matches the color of the pixel you select with a button press. Floodfill changes the matte value of any pixel that matches the color of the pixel you select with a button press and is a neighbor.

Select your transparent pixel with the pointer and press a button. The image is redisplayed with any transparent pixels recolored to the background color. You can select other pixels or areas to force to transparent. When you are satisfied, press Return.

Finally, choose Save from the command menu and write your GIF image to a file. Note that setting transparency works best on a TrueColor or DirectColor visual. If your server only exports colormapped visuals you will need to use a Standard Colormap to set transparency.

 xstdcmap -best
 display -map list image.gif
 choose Matte Edit
 select your transparent pixel then press Return
 choose Save

If you do not have the xstdcmap(1) program, try

 display -visual TrueColor image.gif

4. How can I stop the filenames from changing in the title bar of the animate(1) image window?: Animate updates the image file name in the title bar of the image window as each image is displayed from the image sequence. To display just a single name that will not change, use -title:

 animate -title "My Image Sequence" images.

5. The image grabbed by import(1) does not look like the image on my X server. What's wrong?: Use the -descend option:

 import -descend image.miff

or set this X resource:

 import.descend: True

By default, import quickly grabs the image from the X server. However, it may not always have the correct colors in some areas. This can happen when a subwindow has a different colormap than its parent. With -descend, import descends the window hierarchy. Descending involves grabbing the image and colormap of each window or subwindow associated with the window you select and compositing it on a blank canvas. This can be significantly slower than just grabbing the top-level window but ensures the correct image.

6. How do I animate a digital YUV image sequence?: Suppose your sequence is 72 352x240 frames titled frame0.Y, frame0.U, frame0.V, frame1.Y, frame1.U, etc. Use this command:

 animate -geometry 352x240 -scene 0-71 yuv3:frame%d

7. How do I view only the red channel of an RGB image?: Use the -gamma option, for example,

 display -gamma 1.0,0.0,0.0 image.miff

8. How do I change the default PostScript page size?: The default dimensions of a PostScript page is 612x792. If you prefer another default, change the page geometries (PSPageGeometry) in magick/image.h and recompile.
9. When I display or convert an image, I get Memory allocation error. What can I do?: Memory allocation is a complex topic in GraphicsMagick and image processing requires a lot of memory. GraphicsMagick tries to take best advantage of the resources available by optimizing its use of virtual memory. Virtual memory is normally the amount of RAM (Random Access Memory) available to the process plus the amount of free space in the system paging area (known as "swap" under Unix, or a "page file" under Windows). In addition to the RAM and the paging area, GraphicsMagick is able to expand the amount of virtual memory available by using memory-mapped files which cause the file to be treated as extra memory. A piece of hardware known as the Memory Management Unit (MMU) performs the magic which allows the system paging area and memory-mapped files to be treated as more memory by your system's CPU.; Usually when a memory allocation error occurs, it is because the system's paging area is full, or the programs memory (heap) is fragmented badly enough that there is no large-enough block of memory available to satisfy the request. In some cases the operating system may artificially limit the memory available to the program.; Failures of small memory allocations are generally considered fatal by GraphicsMagick. If it is impossible to allocate even a little bit of memory, then there is no point in continuing. When large memory allocations associated with allocating memory for image pixels fail, GraphicsMagick uses that as a key to know that it should start using memory-mapped temporary files to increase virtual memory. Under Unix and other POSIX-compliant systems, these memory-mapped temporary files are created in either the system default location (e.g. /var/tmp) or the directory set by the TMPDIR environment variable. Under Windows, temporary files are created in the directory set by the TEMP or TMP environment variable.; If the temporary file directory is too small, or is itself mapped to the system's paging area (no win!), then GraphicsMagick will fail to allocate more virtual memory via the temporary file and will return an error.; The single biggest factor in how much memory is required by GraphicsMagick is the QuantumDepth setting when it was compiled. The amount of memory (in bytes) required to store a single image in memory is may be calculated via the equation (QuantumDepth*Rows*Columns*5)/8. As a means of example, the following table shows the amount of memory consumed by a single 1024x768 image using the supported QuantumDepth settings:; Performing an image processing operation may require that several images be in memory at one time. In the case of animations, hundreds of images may be in memory at one time.

QuantumDepth	Virtual Memory
8	3MB
16	8MB
32	15MB

GraphicsMagick is designed to be general purpose. It can display many image storage formats (Monochrome, PseudoColor, or TrueColor) on many different types of X visuals (StaticGray, StaticColor, PseudoColor, GrayScale, DirectColor, or TrueColor). To support all these combinations of image storage formats and X visuals, extra memory is required. Additionally, animate and montage store an entire image sequence in memory.

It is recommended that systems used to run GraphicsMagick have at least 96MB of RAM and 140MB free in their paging area. Systems used to process large images (do the math!) may require considerably more memory to operate efficiently. RAM is typically 1000 times faster than disk, so it is important to keep as much data in RAM as possible (buy lots of RAM). The temporary file area should have plenty of free space. The size of the temporary file area is usually the deciding factor as to whether GraphicsMagick is able to complete an operation. With sufficient free disk space, GraphicsMagick is primarily limited by your CPU and operating system's ability to address memory. GraphicsMagick has been used to process images 20K by 20K pixels in size!
10. How do I concatenate three images left-to-right with no borders, frames, or text?: Assume your three images are called image1.ppm, image2.ppm, and image3.ppm. Type

 montage -mode concatenate -tile 3x1 image1.ppm image2.ppm \
 image3.ppm concatenated.miff

To concatenate the images top-to-bottom, use -tile 1x3.

For more control over the placement of an image, use composite. First create a matte image and position your images onto the matte. For example,

 convert -size 350x500 xc:black composite.miff
 composite -geometry +0+0 composite.miff image1.gif composite.miff
 composite -geometry "+1"00+0 composite.miff image2.gif composite.miff
 composite -geometry +0+300 composite.miff image3.gif composite.miff
 composite -geometry +0+375 composite.miff image4.gif composite.miff

11. How do I create a GIF animation sequence to display within Netscape?: Use convert with the -delay and -page options. The -delay option is used to specify the delay in 1/100ths of a second between the display of each frame of the animation. For example,

 convert -delay 20 frame*.gif animation.gif

You can also declare specific delays for each frame of the image sequence. For example, if the delay was 20, 10, and 5, use

 convert -delay 20 frame1.gif -delay 10 frame2.gif \
 -delay 5 frame3.gif animation.gif

Use -page to specify the left and top locations of the image frame:

 convert frame1.gif -page +50"+1"00 frame2.gif -page +0"+1"00 \
 frame3.gif animation.gif

Finally, if you want the image to loop within Netscape, use -loop:

 convert -loop 50 frame*.gif animation.gif

For further information about GIF animation, see GIF Animation on the WWW.