ImageMagick v6 Examples --
Image File Handling

Index

ImageMagick Examples Preface and Index

Image Formats Summary

Reading Images

• Read Modifiers
• Compressed Images

Saving Images

• Filename Percent Escapes
• GZipped Compressed Images
• Saved Attributes
• Encrypted Images
• Writing a Multi-Image Sequence
• Starting Sequence (Scene) Number
• Writing an Image, Multiple Times

Special Output File Formats (Specific to IM)

miff:   info:   null:   txt:   histogram:   mpr:   mpc:   inline:  

ephemeral: -- Auto-delete after read

show:, win:, and x: -- Display Images Directly

x: -- Reading from a X Window Display

Delegates and Coders for Image Formats

• Input Delegate Example
• Output Delegate Example
• Spawning External Commands
• Listing Delegates and Source Files
• Postscript and PDF Delegates
• Direct Delegate Format Conversion
• Other Delegate Examples

Really Massive Image Handling

Image Formats Summary

Reading Images

  logo:      granite:     rose:

  -size 30x30  xc:red
  -size 30x30  gradient:yellow-limegreen
  -size 30x30  pattern:fishscales
  import:

  -size 30x30  tile:pattern:gray95

When a prefix file format is given, any suffix given as part of the filename does not have any bearing on the way the file is read. This is in fact vital when reading some file formats such as the "text:" verses the "txt:" file format handling. Of course if a image generator actually reads in a image file to process it in a special way (for example "tile:") then the suffix (or prefix) file formats will again become important, as it was in the last example.

  montage  '*.jpg' -geometry 50x50+2+2  image_index.gif

convert http://www.cit.gu.edu.au/~anthony/images/anthony_castle.gif \ -resize 100x100 castle_logo.png

echo "rose: tree.gif" |\ convert @- -frame 5x5+2+2 +append file_list.gif

Read Modifiers

'[#]' '[#-#]' '[#,#,#]' [#,#-#,#]'.

Will select specific sub-frames from a multi-image file format from the image that has been read in. The given number '#' index specifies the frame number to read. Multiple indexes can be specified in either comma order or as a index range.

The image index start at zero for the first image, 1 for the second and so on. If you specify a negative index then the count is from the end of the image sequence, in reverse order, -1 for the last image, -2 for the second last image.

This is exactly the same convention as used for the Image Sequence Operations.

For example

convert document.pdf'[0]' first_page_of_pdf.gif convert animation.gif'[1-3]' second_to_fourth_frames.gif convert animation.gif'[-1,2]' last_then_the_third_frame.gif

You can also get IM to read images based on a list of numbers. For example..

convert 'image_%03d.png[5-7]' ...

will read in the files "image_005.png", "image_006.png", and "image_007.png". With this method you can not use a negative index.

'[#x#]'

From IM version 6.2.6-2 a new modifier was added to help IM users to handle very very large images.

This modifier will resize the image that was just read in, immediately before that image is added to the other images already in memory. For example a small image can be enlarged as part of the image read.

convert pattern:gray95'[60x60]' enlarged_dots.gif

The modifier is most important when you are attempting to read in lots of very very large images, as each image will be resized before the next image is read, producing a substantial saving in total memory needed to handle those images.

For example instead of...

montage '*.tiff' -geometry 100x100+5+5 -frame 4 index.jpg

which reads all the tiff files in first, then resizes them. You can instead do...

montage '*.tiff[100x100]' -geometry 100x100+5+5 -frame 4 index.jpg

This will read each image in, and resizes it, before proceeding to the next image. Resulting in far less memory usage, and possibly prevent disk swapping (thrashing), when memory limits are reached.

For JPEG images I recommend you use something like...

montage -size 200x200 '*.jpg[100x100]' -strip \ -geometry 100x100+5+5 -frame 4 index.png

Note that the "-size" setting has a special meaning for JPEG image format reading. It is passed to the JPEG library and limits the reading in the JPEG image produce an image that size or slightly larger. In other words it further limits the memory usage for large JPEG images, before the input modifier resizes the image down to the actual size wanted. See Reading JPEG Images. Only the JPEG image file format uses "-size" in this way. You can not use it for TIFF or PNG image file formats, which is why the input resize modifier was developed for general use.

'[#x#+#+#]'

From IM v6.3.1 if you also add a offset the above becomes a crop of the image being read in.

For example, To get a smaller 600x400 pixel tile from a very large image.

convert 'image.png[600x400+1900+2900]' tileimage.png

This however will read in the entire image into memory then crop it before it is finally added to the current image sequence.

If you want to handle really large images I suggest you look at the "stream" command and pipe you image into the "convert" command for further processing. See Massive Image Handling below.

The PNG format includes "gzip" compression as part of its format specification. In this case the first digit of the two digit PNG "-quality" setting defines the level of compression. For more detail see PNG Image File Format examples.

WARNING: Be very careful when passing a user provided argument to IM in a script, insuring that the argument is what you expect. You do not want to let a web image processing script return a image of the system password file for example.

Compressing Images

Under Construction

IM will also read these compressed files via the appropriate commands.

After that you can refer to the image in the browser as most web servers and
browsers will support sending the compressed file, compressed and uncompress
it for use at the other end.

Compressed XPixmap (xpm) images is also automatically handled by the Xpixmap
library, so you can use that format directly in many X window programs.

Saving Images

convert tree.gif GIF:tree_image

convert tree.gif -resize 1x3\! txt:-

convert tree.gif -resize 200% miff:- | identify -

Filename Percent Escapes

convert rose: -set filename:mysize "%wx%h" 'rose_%[filename:mysize].png'

Automatic GZip Suffix

convert rose: -compress none rose.gif.gz

convert rose: rose.gif

Saved Attributes

Under Construction

Other Settings specific to image writing....
    -depth  -quality  -compress -type  -loop
    -set label   -set comment
Also see Image Depth,
Image Type,
JPEG Quality,
PNG Quality.
GIF loop.

Talk about file compressions, which are part of various image formats.

Different compressions are used for different image formats.

Especially the JPEG to TIFF compression change needed.

Using or "-compress
None" and "-compress" NetPBM text/binary format selection.

The GIF compression and the copyright patent.

Other than using IM to reduce -quality or changing the format to something
else the -compression option is rarely used.  Often it is only used internally
by IM to save images using the same compression the image was read with.

Encrypted Images

Writing a Multi-Image Sequence - Adjoin Techniques

convert eye.gif news.gif storm.gif +adjoin image.gif

Previous to ImageMagick version 6.2.0 the output filename of the above would have been "image.gif.0" to "image.gif.2". This resulted in many problems due to the loss of the filename suffix, so was changed to add the image number, before the filename suffix.

convert eye.gif news.gif storm.gif +adjoin image_%d.gif

Not only can you use '%d' for a decimal number, but you can use '%x' for a hexadecimal number (lowercase), '%X' for a hexadecimal number (uppercase), or '%o' for an octal number.

If you really want a percent character which is followed by one of these letters, then you will need to double the percent character to escape its meaning. That is you will need to use '%%' to ensure you actually generate a percent symbol.

The '%d' in the output filename actually enables the "+adjoin" setting of ImageMagick, automatically. However while I don't actually need the "+adjoin" in the above, it is probably a good idea to provide it anyway, just so it is clear that you are generating separate images.

  convert image_[0-9].gif  image_[1-9][0-9].gif  animation.gif
  convert image_?.gif  image_??.gif  image_???.gif  animation.gif
  convert image_(?|??|???|????).gif  animation.gif
  convert 'image_%d.gif[0-123]'  animation.gif

convert eye.gif news.gif storm.gif +adjoin image_%03d.gif

Written Scene Numbers

convert null: eye.gif news.gif storm.gif +adjoin image_%01d_of_3.gif rm image_0_of_3.gif

convert eye.gif news.gif storm.gif +adjoin -scene 101 image_%03d.gif

Writing an Image, Multiple Times

convert cyclops.gif -fill lightsteelblue -draw 'color 0,0 floodfill' \ \( +clone -resize x128 -write cyclops_lrg.jpg +delete \) \ \( +clone -resize x96 -write cyclops_big.jpg +delete \) \ \( +clone -resize x64 -write cyclops_med.jpg +delete \) \ -resize x32 cyclops_sml.jpg

Special File Formats (specific to IM)

miff:

is the ImageMagick File Format. The whole image sequence and all the attributes associated with the images are saved in this file format. Of course only ImageMagick commands will read this format, so it is not suitable for long term or transferring between different image processing packages.

The "miff:" file formats primary purpose is as a intermediate save format during large image processing scripts. Or when 'pipelining' an image from one IM command to another. See the last example for one such pipeline.

For those interested in parsing this format, it is a semi-text format consisting of a ascii header of image attributes, a line containing a single formfeed, followed by the raw image data as a binary. This header is itself a useful way of extracting basic image information in various image processing processing scripts.

For example here are I use a GNU-sed command to show all the attributes (the few that there are), of the built-in "rose:" image.

convert rose: miff:- | sed -n '1,/^\f$/{ /^\f$/d; p; }'

This is actually quite useful as it reveals all the current settings flags and meta data that IM knows about the image. However there is also statistics, as these are generated by either the "identify" command, the "-identify" operator or the special "info:" format; if requested with a "-verbose" option. (see next)

The "miff:" format can also handle multiple images, and in fact does so simply by appending the images together.

This means you do not need to process all the images, by a single command. You can put the command in a loop, and just output MIFF format images, one after the other, to the loops standard output. That result can then be piped directly into a single command to generate montages, collages, animations, or something else.

For example the following generates a list of colors starting with the letter 'b', then uses a separate convert command to generate label for each color, one label at a time. These are then montaged together to produce a simple color table.

convert -list color | egrep '^b' | \ while read color junk; do \ convert -label $color -size 70x20 xc:$color miff:-; \ done |\ montage - -frame 5 -tile 6x -geometry +2+2 \ -background none color_table.png

The above was also converted into a script "show_colors" which you can use to search for and find colors to use in your image.

This looped image output technique also means you can use code like "-write miff:-", to output a miff format image from multiple places in a single command. Each image will be automatically append together in the final output stream.

This stream can not only be feed into "montage", say to debug image processing, but also into "display" (with some timing settings) as a simple slide show. Finally this format (while not compressed) can handle ANY type image IM knows about at any depth or quality level the IM was compiled with.

It is about the most ideal format to use for temporary images, and pipelined image commands you can use, though IM is the only one that can read it.

A very useful image file format, indeed.

info:

The "info:" file format (added in IM v6.2.4) does NOT output an actual image! This format basically outputs the same information that the ImageMagick "identify" command will output.

Like "identify" this output format is controlled by the "-format" and "-verbose" options allowing you to output just the specific information you are interested in, as defined by the Image Property Escapes page.

For example instead of piping a MIFF image to "identify" as we did above (see Saving Images), we could have used the following, to retrieve the single line identification of the resulting image format.

convert granite: info:-

Of course you can use a "-format" setting to output the desired information in a specific and more parsable way.

What is so useful about "info:" is that you can now produce your image, while extracting extra information about it, at the same time. This is done by using the "-write" operator to save this special image format to a file (or the commands normal standard output).

	convert rose: -shave 12x0 -repage 64x64+9+9 \ -format '%wx%h %g' -write info:info_paged.txt paged.gif

There is also a "-identify" operator that is equivalent using "-write info:" to output image identification information to standard output, or "-print" output operator. This make it even easier to monitor what is happening to your images when debugging your IM commands.

For example...

	convert logo: -identify \ -trim -identify \ +repage -identify \ -resize 80x80\! -identify \ logo_thumbnail.gif

Here you can see how "-trim" reduced the size of the image but preserves the 'crop' information of what part of the image was trimmed, then the "+repage" removing that extra 'canvas' or 'page' information. And so on.

Also like the "identify" command, both "info:" and "-identify", will become much more verbose if the "-verbose" setting is turned on. Here I limit the long output to just the first few lines, just so you can get a bit of an idea about it.

convert rose: -verbose info: | head

The "-verbose" setting will also cause extra information about images being read in or out, to be printed to the standard error (with the exception of the "info:" format). It also causes some operators like "-colors" to output additional information. As such you may like to turn it off again after using it with either "-identify" or the "info:" format. For example    "-verbose -write info:image_info.txt +verbose"    or    "-verbose -identify +verbose" .

Scripted reading of the output from any form of "identify", should do so in a case in-sensitive way. This insures better backward compatibility between different versions of ImageMagick.

NOTE: "info:" (and "-identify") is only an output format, producing the same output as the "identify" command. You can not read, or create an image using the "info:" file format.

null:

As an output format, this will just 'junk' the image results. As such if used as the final argument in a "convert", "montage", or "composite" command the final result will not be saved!

Why? Well it may be that you are more interested in specific images, generated during image processing rather than the overall result, especially when debugging.

For example, here we extract and save one image, from an image sequence, then junk all the other images using "null:".

convert eye.gif news.gif storm.gif tree.gif rose: logo: cyclops.gif \ \( -clone 2 -write write_storm.gif \) null:

This is a lot simpler than attempting to delete all the other images one at a time.

As a input image format however, "null:" will generate a special placeholder image of a single transparent pixel, with with a special 'null source' flag, in the current image sequence.

This special image is especially important to Leave Gaps in a Montage, and as a list separator for multi-image Layer Composition. It is closely related to another special image format known as a 'missed image', that can be generated for operations like "-crop". This image format is produced when an operation produces an empty or non-sensible result. Both images are a single transparent pixel, and as such "null:" images will also be treated as if it is a 'missed image'.

At this time there is no method to remove any "null:" or even 'missed image', from the current image sequence. However such a method has been proposed. Mail me if you find you need such a method.

txt:

This is a simple ASCII text file, which basically lists each pixel in the image, one per line. It is not a general text to image converter, for that see Multi-line Text Files Examples.

For example here is a "netscape:" image scale to a 2x2 pixel image, then listed using a "txt:" image format.

convert netscape: -scale 2x2\! txt_netscape.txt

The first line (header) of the image is packed with the basic information about the image. The information consists of...

File Magic: The image header defines this file as a the special IM text image format (EG a "ImageMagick pixel enumeration" file), this is known in computing circles as the files 'magic' or the code string which identifies this file as being this specific file format.

Image Size: The next two numbers define the size of the image contained in this file. Multiplying these numbers together will also tell you how many lines should follow the header to fully define the image.

MaxValue: The last number in the header defines the 'maximum value' of the image data that is possible. In the above examples this was '255' which is a result of using a 8 bit depth.

The reason it output the built-in "rose:" image at this depth is because it was defined internally using 8-bit values, and as such IM preserved this depth level for the image. See the section on the depth setting for more information.

But you can override the depth setting (up to the limit of your IM's Q or Compile-time Quality setting, by changing the images "-depth". For example here I output the color values as 16 bit (or values from 0 to 65535)...

convert -depth 16 netscape: -scale 2x2\! txt_netscape_16.txt

At this time you can not set a specific 'Maximum Value' to use in the output file format. You can only define a different value in terms of the current "-depth" setting, making the maximum value equal to 2^depth-1.

Colorspace: The last item in the header defines the colorspace of the image being output. If the image contained any transparency, a final letter 'a' (for alpha) is also appended to the colorspace name, and an extra column of numbers added between parenthesis. Grayscale images will use the 'rgb' format, though all three numbers are the same value.

For example here is the same image using a colorspace of 'LAB' with an alpha channel added!

convert netscape: -scale 2x2\! -colorspace LAB -matte txt_cspace_lab.txt

After the initial header are the Pixel Data lines, one per pixel in the image.

Coordinates: The first two numbers up to the colon ':' is the pixel position, starting from 0.

Color Values: After this the color values for the pixel (from 0 to the MaxValue given in the header) is given in parenthesis, with anywhere from 3 to 5 numbers depending on the current colorspace for the image. Spaces are optional so caution is advised when parsing the numbers in parenthesis.

Color Comments: Anything that follows the numbers in parenthesis is regarded as comment. IM will fill in extra information on the pixel color using formats that it can parse as a color argument (See "-fill" manual entry for details of these color specifications).

The color comments are however variable, and may output RGB() or color names depending of the pixel data given. Also exactly what color comment is provided is highly dependant on the IM version you are using, especially in early IM v6 versions and before. There is no guarantee that this comment area will not change again in the future, so it is best not to rely on it. IM doesn't.

Here is an example of correctly reading a Pixel Enumeration in a shell script. The exact format of the TXT image is defined by the convert command, then 'tail' is used to junk the header, 'tr' to character replace every non-number character with a single space, so that the later 'while' can read it easily, junking any comment numbers that may have been left.

convert rose: -resize 3x2\! -depth 8 -colorspace RGB +matte txt:- | tail -n +2 | tr -cs '0-9\n' ' ' | while read x y r g b junk; do echo "$x,$y = rgb($r,$g,$b)" done

Reading TXT images is also valid. You do not need to define ALL the pixels in the image. In fact you do not even need to have the pixels in the correct order. ImageMagick will just read each of the pixel in turn and 'draw' it onto a blank image canvas. Only the numbers in the parenthesis on each line is used for this.

The initial blank canvas, is normally cleared as set to the current background color. As such any pixel not provided by a "txt:" image, will be left as this color.

The "txt:" format is especially useful with the "-unique-colors" operator, which replaces each image in the current image sequence with a new image containing one pixel for each unique color found. When this is output to a "txt:" format file, you get a basic summary of the colors contained in an image (though not their counts, or histogram).

For example here are the colors used by the tree image. As GIF can only use 8 bit numbers, I also chose to output the file the same "-depth".

	convert tree.gif -unique-colors -depth 8 txt:-

There is another alternative to using the IM "txt:" format using the various NetPBM image file formats. IM by default outputs this format as binary, but you can turn off "-compress" to output a ASCII text version of the NetPBM format. For example.

convert tree.gif -unique-colors -compress None -depth 8 tree_netpbm.ppm

You may notice that the numbers in the above matches the number in the IM's Enumerated Pixel ("txt:") format. See Resized Gradient for some examples of generating a NetPBM format image for IM to read.

If you just want the color of a specific pixel you can crop the image down to one pixel, and output it as a "txt:" image.

convert rose: -crop 1x1+12+26 txt:

Or you can use a special FX Escape Format to output the color in a form directly usable by IM.

convert rose: -format '%[pixel:u.p{12,26}]' info:

See also Extracting Image Colors.

histogram:

This is actually the "miff:" image format, but with a very large image comment that contains a complete count of all the colors within the image. That is in the "miff:" text header 'Comment={...}' attribute.

For example, here we again list the colors present in the "tree" image, but this time including the pixel count for each color. The text histogram comment is extracted from the "histogram:" image using a secondary "info:" formatted identify.

	convert tree.gif -format %c histogram:info:-

The "info:" output format was added to IM v6.2.4. For IM versions before this use.. convert tree.gif histogram:- | identify -format %c -

You will note that the format is almost exactly the same as that of the previous TXT, or IM Pixel Enumeration Image format, including the comments on the color values. The only difference is that the X,Y location has been replaced by a count of the number of pixels.

The image itself is a histogram graph, 256x200 pixels in size. The x-axis is color value (0-255) and the y-axis is pixel count (normalized to the number of pixels). The histogram for each channel is displayed in the color it represents, and added together. Thus, red and blue overlap to make magenta. In other words with color channel has its own separate histogram.

If you want the image converted to some other format, just save it into that format. "histogram:" is a special image processing format. It will convert the image, then output in the format specified by the filename suffix or further "format:" codes. convert rose: histogram:histogram.gif

An image that is very dark will be heavily weighted to the left, while a light image will be heavily weighted to the right. Mid-tones, likewise, are represented in the middle.

To see this better here I separate the histograms for each of the color channels. I also strip the histogram text comment, and resize the image for display.

convert histogram.gif -strip -resize 50% -separate histogram-%d.gif

Red	Green	Blue

For the "rose:" image above you will see that red is spread more showing its vital importance in the image. On the other hand green and blue spikes on the left, showing that is has very little influence on the image at all.

If you are more interesting in the brightness of an image rather than its colors, convert the image to a gray-scale before generating a "histogram:" image. image generated by 50%. convert rose: -colorspace Gray \ histogram:histogram_grayscale.gif

As you can see the histogram of a gray-scale image is a little different. As the predominate red color become more of a mid-tone grey color, producing a spike in the center of the histogram. Also the small area of off-white in the image now produces a distinct spike at the extreme right of the graph.

The completely empty space at the extreme left also shows that there are no dark patches in the image at all.

On the other hand a better 'global' histogram can be generated by simply separating all the color channels in the original image and appeneding. The resulting histogram is a representation of all the color values regarless of which channel that value is from. convert rose: -separate -append \ histogram:histogram_values.gif

Unfortunately as "histogram:" is an output format, you will either need to 'pipe' the image into another command, save it to disk, or use the special "mpr:" save/read, if you want to process the image further. See example in "mpr:" below.

mpr:{label}

(memory program register) will save the image into memory, rather and onto disk. As such if you want to save an image for use latter, in a complex image operation you can do so.

Of course as you are saving into memory, you will need to do this as a Write operation, and not when the command is about to exit, and the commands memory is returned back to the system.

The 'label' given to "mpr:" can be anything you like, it is only a label on where the image was saved in memory. It can even be just numbers for people who do scripting and don't want to deal with names.

After you have saved an image see below), you can then read in the image again, from the same 'labelled' memory location, as many times as you like. For example...

convert tree.gif -write mpr:tree +delete \ mpr:tree mpr:tree mpr:tree +append mpr.gif

In many ways this is like using Clone but by taking the image completely out of the current image sequence.

The best feature of this method is that it also allows the use settings and operations that only work on image input. For example, using it with the input image "tile:" operator to tile an image over a larger area.

convert tree.gif -flip -write mpr:tree +delete \ -size 64x64 tile:mpr:tree mpr_tile.gif

You can also use "mpr:" to grab the output of some of the special output image format filters for further processing. For example here we grab the output image from "histogram:" and continue to process it to make a smaller histogram chart, before actually writing it to a file for real.

convert rose: -write histogram:mpr:hgram +delete \ mpr:hgram -strip -resize 25% histogram_resized.gif

The "mpr:" in-memory save is actually the only way you can re-use images already in-memory through special I/O filters such as "histogram:" or See "tile:".

The same is true for the special options that take an image, such as "-tile" or for "Color Mapping" images using another image as a source. See Multi-image Color Maps

It is also the only way to use the -draw 'image' method to overlay images using a generated in-memory image, though there are lots of other better methods to do this.

Note that "mpr:" image actually saves the whole image sequence and not just one image. It is a bit like taking a snapshot of the current image sequence so you can reload it later on for further processing. This for example allow you to take copies of a whole animation sequence, for duplicating or cloning, without needing to know how many images are actually involved. See Layers Composition for an example of doing this.

The Image Cloning operator cannot generally handle a unknown variable number of images, and in fact before the Clone operator was added "mpr:" was the only method available for duplicating in-memory images, without using intermediate disk files.

mpc:

Is a special IM specific save format that is designed with really large images in mind. Basically is is a memory-mapped disk file of program memory, that is saved to disk as two binary files, a ".mpc" holding the images meta-data, and a ".cache" holding the images pixel-cache.

The "MPC:" format saves two images.

For example...

convert very_big_image.tif very_big_image.mpc

will create two files on disk. A small "very_big_image.mpc" file and a special memory dump file called "very_big_image.cache". The second file size will likely be larger that any other image file format, and will only be usable on machines with the exact same hardware and operating system version, as what it was created on.

However the file does not need to be 'read in' or 'decoded' but can be directly 'paged' into computer memory and used exactly as-is, without any processing overhead, only lots of disk space. In other words it has a next to instant in reading time, though disk speed access time. No decoding needed.

Because the image is 'memory-ready' it is especially useful for temporary images of all sizes as it will be usable immediately by the next IM command you issue. But remember two files are generated and they will be larger than a normal image filesize, so be careful of your disk usage.

My own IM scripts do this. For example see the scripts "de-pixelate", and "divide_vert", which make use of quite a few temporary image files for image processing operations.

This can be extremely useful for scripts or Mogrify Alpha Compositing that needs to be able to read the same image, over and over and over again, as IM does not have decode the image, or use up lots of memory just to store it.

This is also very useful for processing a very large MPC copy of the image, where you must extract or crop a smaller section of the image for the for actual processing. However as most image operations actually make clone copies of images during processing, a new in-memory copy could be made. So some care is still needed.

For more information see Really Massive Image Handling below.

inline:{base64_file|data:base64_data}

Inline images let you define the image in base64 encoding directly. This is more typically used as part of API's as an alternative to 'blobs'.

For example to read a base64 encoded image use...

inline:base64_image.txt

Or put the image data directly on the command line...

inline:data:;base64,/9j/4AAQSk...knrn//2Q==

The commandline option input is restricted to 5000 characters, longer base64 images will need to be input via a file.

ephemeral:{image_file}

Read and then Delete this image file.

This is a special image reading file format which will cause IM to delete the given image file after that file has been read into memory.

This is very dangerous and should be used with extreme caution.

It is used for example in Delegate Spawning. Here the backgrounded delegate will read the input image, then deletes it to notify the foreground process, that it is ready to become independent. The main program then cleansup and continues its image processing, or exits as the case may be.

The "show:" image output delegate uses this with the "display" command to background a on screen image display before continuing or exiting the original program. (see bewol)

show:, win: and x: -- Display images directly on screen

These are special output formats that will which will directly display the image result to your screen. Instead of saving the image into a file, it just displays the result.

This is very useful for quick testing IM commands to see what the results will be, and is highly recommended for this purpose. However they are only very simple versions of the "display" and "animate" command.

For example, get a fast summary of images in a directory...

montage *.jpg show:

See the areas that are different between two images...

compare image1.png image2.png show:

All the formats actuall call on the "display" program to perform ther task. However they are handled in different ways.

For example 'show:' (or for windows systems 'win:') will use a Spawning Delegate. this means that once the image had been read for display, the original command will exit, returning you the command line prompt.

On the other hand using 'x:' will wait for you to quit the display window before allowing the original command to exit.

Unfortunately none of these methods will display animations very well.

x: (as input) - Reading an X Window Display

You can also read the current X window display using the "x:" operator, in much the same way as you can with the "import command. In fact without options it acts exactly like the "import" command. Use the left button to select the window to grab a copy of, or mark out an area using the middle button.

For example, to select a window using your mouse, then display the window just grabbed in another window (exit when grabbed window is displayed)...

convert x: show:

WARNING. if you grab a window that is unmapped (iconized), or another window is over the top of it, the image contents will contain either a blank area, or the contents of the overlaping window!!! So make sure when grabbing a window that window fully visible on screen.

To grab the whole display use 'root' for the window name.

convert x:'root' full_screen_dump.jpg

Or use the Read Modifiers to grab a specific area of the display.

convert x:'root[300x400+879+122]' part_screen_dump.jpg

Providing a window name you can grab a specific window. For example this will grab the window titled 'MailEd'...

convert x:'MailEd' window.jpg

However that does really not work well, as often you have multiple windows with the same name, or the name of the window just can't be determined.

The better way is to tell IM the exact window wanted using a "X Window ID" which is the number that the X display uses to uniquely identify a specific window (or child window).

Most terminal programs will tell you the X Window ID they are using to display text in the environment variable "WINDOWID". As such if you run this from a command line of a XTerm, or Gnome Terminal, you will grab a copy of the current terminal window.

convert x:$WINDOWID this_terminal.png

The other way is to lookup the X Window ID using the "xwininfo" command. This command will give you details of the window, (name, title, size, placement, parent and child windows, etc), which you can either select, or just a list of ALL the windows.

For example, find all windows with "Mozilla Firefox" in the title or name...

xwininfo -root -all | grep "Mozilla Firefox"

I can then extract the X Window ID of the window I want from the output of the above.

Now for some fun... Here I grab the contents of my current terminal, draw some stuff into it, and then use the "display" to draw it back into the same terminal window!

window=`xwininfo -children -id $WINDOWID |\ sed -n 's/^ *\(0x[^ ]*\).*/\1/p'`; \ window="${window:-$WINDOWID}"; \ convert x:$window -background black \ -draw 'fill black rectangle 40,40 160,160' \ -draw 'stroke red line 50,50 50,150 line 50,150 150,150' \ -draw 'fill lime circle 110,100 80,100' \ -draw 'stroke dodgerblue line 50,150 150,50' \ png:- |\ display -window $window -

The first command in the above is designed for an XTERM, which requires that the window you "display" into, be the child window of the provided "WINDOWID". The second line falls back to original value of "WINDOWID" if no 'child' window is found, as is the case for a Gnome-Terminal.

Once the window to use is worked out, it is grabed, drawn on, and restored into the terminal window! And presto you have instant graphical output directly into the current terminal window.

Here is a simpler example, this blurs the window contents each time you run it. Try running this a few times, and you find the older commands in the terminal getting more blurred!

window=`xwininfo -children -id $WINDOWID |\ sed -n 's/^ *\(0x[^ ]*\).*/\1/p'`; \ window="${window:-$WINDOWID}"; \ convert x:$window -background black -blur 3x1 png:- |\ display -window $window -

Be warned that while the contents of the terminal are modified, it is only temporary. If you iconify, obscure, or change desktop screens, then go back to the terminal the modifications will be lost as the terminal program re-draws what should be visible in the terminal window.

The above does not work nearly as well for gnome-terminals as for Xterms because the former likes to 're-draw' its window every time it scrolls, where Xterms do not.

Imagine IM scripts that display their results of graphs and other things directly in various windows as part of a larger client program. This is in fact how many postscript viewers, and even many web browsers display output from special sub-programs. That is they have that sub-program directly draw into a provided sub-window.

Experiment, and let me know what you come up with!

Delegates and Coders for Image Formats

Input Delegate Command Example

<?xml version="1.0" encoding="UTF-8"?>
<delegatemap>
  <delegate decode="flip" command="convert '%i' -flip 'miff:%o'"/>
</delegatemap>