ImageMagick v6 Examples --
Multi-Image Layers

Index

ImageMagick Examples Preface and Index

Layers Introduction

Appending Images (-append)

Multiple images with Composite (composite, -geometry)

Composite Images in Convert (-composite, -geometry)

Draw Multiple Images (-draw image)

Flatten Multiple Layers of Images (-flatten, page)

Canvas Expanding Mosaics (-mosaic, -page)

Layer Merging (-layer merge)

Coalesce, a Progressive Flatten (-coalesce)

Compose Methods and Flatten (-compose)

Averaging images together (-average)

Overlaying multiple image onto each other to generate a later 'composite' is generally known as using image 'layering'. These examples involve the combining of multiple images into larger images. Especially with the main 'work horse' operator of image layering within IM, "Flatten" (see below).

---

Layering Images Introduction

As we have previously noted, ImageMagick does not deal with just one image, but a sequence or list of images. This allows you to use IM in two bery special image processing techniques.

You can for example think of each image in the sequence as a single frame in time, so that the whole sequence can be regarded as being a Animation. This will be explored in other IM Example Pages. See Animation Basics.

Alturnativally, you can think of each image in the sequence as Layers of a set of see-thru overhead transparencies. That is each image represents a small part of the final image. For example: the first (lowest) layer can represent a background image. Above that you can have a fuzzy see though shadow, than the next layer image contains the object that casts that shadow. On top of this a layer some text that is written on that object.

Basically then you have a sequence of images or 'layers' that build up the final image on piece at a time. Each image layer can be moved, edited, or modified completely seperatally from any other layer, and even saved into a multi-image file (such as TIFF:, MIFF: or XCF:) or as separate images, for future processing. And that is the point of image layering.

Only when all the images have been created do you Flatten, Mosaic, or Merge all the images into a single final image.

---

Appending Images

Appending is probably the simplist, of the multi-image operations provided to handle multiple images.

Basically it joins the current sequence of images in memory into a column, or a row, without gaps. No form of justification such as centering is (currently) provided, so images are aligned either along their left, or top edges, as appropriate. The "-append" option appends vertically, while the plus form "+append" appends horizontally.

For example here we append a set of letter images together, side-by-side, to form a fancy word, in a similar way that fonts letters are joined together.

The above is similar (in a very basic way) to how fonts are handled. Unlike real fonts you are not limited to just two colors, but can generate some very fancy colorful alphabets from individual character images. Many of these 'image fonts' are available on the WWW for download. A very small set can be found in Anthony's Icon Library, in Fonts for Text and Counters, which is also where I found the above Blue Bubble Font.

Note also how the "+append" operator was done last, on the command line, after all the images that you want to append have been added to the current image sequence.

Append is also commonly used to add a blank area to just one side of an image for text labels or other information. This makes use of the "-background" color to fill in the rest of the space without needed to know the width (or height) of the image. Something that is important for automated image processing scripts.

For example say you want to create some space below an image, so you can draw a text string into it as an image label.

convert rose: -size 15x15 xc:LawnGreen \ -background LawnGreen -append \ -draw "gravity South text 0,0 'Rose'" append_draw.jpg

That is fine for appending space in which to center some text, but what if you want to append an image, such as a label, instead of just making some space?

convert rose: -background LawnGreen label:Rose \ -background white -append append_label.jpg

As you can see appending images of different sizes is not very nice, with the images being left justified (or top justified for horizontal append). Any extra space is then filled with the current "-background" color.

By making mirror images before appending (using "-flop"), then back again afterward, you can right justify the appended images.

convert rose: -background LawnGreen label:Rose \ -background white -flop -append -flop append_right.jpg

It is also posible to center the images being appending by using some trickiness.

convert rose: -background LawnGreen label:Rose \ -bordercolor white -border 100x0 \ -gravity center -crop 200x0+0+0 +repage \ -append -trim append_center.jpg

Essentually we added some extra "-border" space to either side of all the images being appened together, then use a centered column "-crop" to line up the images, before appending. A final "-trim" after the append takes care of the unneeded extra border space.

Older IM's (before v6) do not understand a 'zero' size for "-crop". In that case replace the zero size with a very large number. In this example '200x0+0+0' then becomes something like '200x999999+0+0'. DO NOT use a large number like this for ImageMagick version 6, or it will take a very long time to process.

The biggest problems with this method is that the final trim could over trim into the original images, though they will remain centered according to the original image size. The other problem with this method is that the border size you add, and crop using double the border size, must be larger than the difference between the widest and least wide images. Too large however and you will end up using a lot of computer memory to hold the enlarged images.

It is hoped that a future version of IM will have a 'justify' option, not only for text allignment but also for aligning appended images. This is one the things on the IM 'todo' list, but may be some time before it is implemented.

If you like a simplier and safer solution, but which can not be used in a larger "convert" command, you can do centered appends of a list of images using "montage". See Appending Images with Montage.

You can also use multiple append operations, in the same command without conflict or confusion as to the outcome of the operations.

convert font_{0,0,6,1,2}.gif +append dragon_long.gif \ -background none -append append_multi.gif

Basically we appended a row of images together, then appended a larger image below that. Very simple, and straight forward.

By using parenthesis, you can append just the numbers after the larger image. For example, here append all the numbers together, before appending them vertically to the dragon image we read in before the numbers.

convert dragon_long.gif '(' font_{0,0,6,2,9}.gif +append ')' \ -background none -append append_parenthesis.gif

The parenthesis in the above must be either quoted, or escaped with a backslashed ('\') when used with a UNIX shell, otherwise they will be interpreted by the shell as something completely different.

As only two images were involved we could have just added a "+swap" instead of using parenthesis.

You can take this further to make a whole array of images, and build them either by rows, or by columns.

convert \( font_1.gif font_2.gif font_3.gif +append \) \ \( font_4.gif font_5.gif font_6.gif +append \) \ \( font_7.gif font_8.gif font_9.gif +append \) \ \( -size 32x32 xc:none font_0.gif +append \) \ -background none -append append_array.gif

Technically the first set of parenthesis is not needed, as no images have been read in yet, but it makes the whole thing look uniform and shows the intent of the command, in making an array of images.

See also Montage Concatenation Mode, for an alturnative way of creating arrays of equal sized images.

The "-append" operator will only append the actual images, and does not make use the virtual canvas (image page) size of offset. However the virtual canvas information seems to be left in a funny state with the canvas sizes being added together and the offset set to some undefined value. This may be regarded as a bug, and means either the input images or result should have the virtual canvas reset using "+repage", before saving, or using the image in operations where this information can become important. This situation will probably not be fixed in some future expandsion of the operation. Caution is thus advised, especially if re-appending Tile Cropped images.

---

Multiple images with Composite

The normal method of combining two images together using ImageMagick is though the "composite" command. This command however is designed to only combine only two images. This of course does not stop you from using it to layer multiple images, one image at a time...

convert -size 100x100 xc:skyblue composite.gif composite -geometry +5+10 balloon.gif composite.gif composite.gif composite -geometry +35+30 medical.gif composite.gif composite.gif composite -geometry +62+50 present.gif composite.gif composite.gif composite -geometry +10+55 shading.gif composite.gif composite.gif

As all input images are read in by ImageMagick BEFORE the output image is opened, you can output to one of the input images. This allows you to work on the same image over and over, as above, without problems. Do not do this with a lossy image format like "JPEG" as the format errors are accumulative, and the base image will quickly degrade.

You can also resize the overlayed image as well as position it using the "-geometry" setting.

convert -size 100x100 xc:skyblue comp_resize.gif composite -geometry 40x40+5+10 balloon.gif comp_resize.gif comp_resize.gif composite -geometry +35+30 medical.gif comp_resize.gif comp_resize.gif composite -geometry 24x24+62+50 present.gif comp_resize.gif comp_resize.gif composite -geometry 16x16+10+55 shading.gif comp_resize.gif comp_resize.gif

The "composite" command also has a few other advantages in that you can control the way the image is drawn onto the background with the "-compose" option, and its relative position is effected by the "-gravity" setting.

You can also "-tile" the overlay so that it will just cover the background image, without needing to specify tile limits. Something only available in when using "composite".

The big disadvantage with this method is that you are using multiple commands, and IM has to write-out the working image, either to a pipeline, or to disk, for the next command to read-in again.

To find more examples of using the "composite" command, to overlay images on top of other images, see "Annotating by Overlaying Images" and "Image Positioning using Gravity".

---

Composite Images in Convert

With ImageMagick version 6 the "-composite" operator, is now available as an 'image operator' within the "convert" command. For more details see Convert -composite Operator. This allows you to do the same as the above, but all in one command.

convert -size 100x100 xc:skyblue \ balloon.gif -geometry +5+10 -composite \ medical.gif -geometry +35+30 -composite \ present.gif -geometry +62+50 -composite \ shading.gif -geometry +10+55 -composite \ compose.gif

Now the "-geometry" is is a very special operator that not only sets an overlay position for the next "-composite" operation, it also "-resize" the last image (and only the last image) in the current image sequence.

convert -size 100x100 xc:skyblue \ balloon.gif -geometry 40x40+5+10 -composite \ medical.gif -geometry +35+30 -composite \ present.gif -geometry 24x24+62+50 -composite \ shading.gif -geometry 16x16+10+55 -composite \ compose_resize.gif

There are of course features in "composite", not available in any form of "convert" image overlaying. See the composite command summery.

Image positions are effected by "-gravity" for thier relative placement, which is not the case for the next set of image overlay options.

---

Draw Multiple Images

Also using "convert" you can also use "-draw" to draw the images onto the background frame.

convert -size 100x100 xc:skyblue \ -draw "image over 5,10 0,0 'balloon.gif'" \ -draw "image over 35,30 0,0 'medical.gif'" \ -draw "image over 62,50 0,0 'present.gif'" \ -draw "image over 10,55 0,0 'shading.gif'" \ drawn.gif

You can of course also specify a resize for the overlaid image too..

convert -size 100x100 xc:skyblue \ -draw "image over 5,10 40,40 'balloon.gif'" \ -draw "image over 35,30 0,0 'medical.gif'" \ -draw "image over 62,50 24,24 'present.gif'" \ -draw "image over 10,55 16,16 'shading.gif'" \ drawn_resize.gif

As of IM version 6 the position of drawn images are "-gravity" effected, just like text. But this is NOT true in the previous IM version 5.5.7.   See examples of this in "Image Positioning using Gravity".

---

Flatten Multiple Image Layers

The "-flatten" image list operator, is very similar to last few example sections.

It will basically "Alpha Compose" all the given images together to form one single image. However the image positions are specified using there current Virtual Canvas, or Page offset.

For example, here I create a nice canvas, and specify each of the images I want to overlay onto that canvas.

convert -size 100x100 xc:skyblue \ -fill dodgerblue -draw 'circle 50,50 15,25' \ -page +5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -flatten flatten_canvas.gif

However you don't need to create an initial canvas as we did above, you can instead let "-flatten" create one for you. The canvas color will be the current "-background" color, while its size is defined by the first images Virtual Canvas size.

convert -page 100x100+5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -flatten flatten_page.gif

While the "-gravity" setting will effect image placement defined using "-geometry" settings, it will not effect image positioning using virtual canvas offsets set via the "-page" setting. This is part of the defination of such offsets. If placement with "-gravity" is need look at either the above multi-image composition methods, or the special Layers Composition method that can handle both positioning methods simultaniously.

If any image does not appear in the defined virtual canvas area, it will be either clipped, or ignored, as appropriate. For example here we used a smaller canvas size, causing the later images not to appear completely on that canvas.

convert -page 75x75+5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -flatten flatten_bounds.gif

The normal use of "-flatten" is to merge multiple 'layers' of images together.

That is you can be generating various parts of a larger image, usally using Parenthesis to limit image operators to the a single 'layer' image being generated, and then flatten the final result together.

For example one typical use is to create a Shadow Image layer, onto which the original image is flattened. For example...

convert balloon.gif \( +clone -background navy -shadow 80x3+5+5 \) +swap \ -background none -flatten flatten_shadow.png

Note that as I want the shadow under the original image, I needed to swap the two images place them in the right order.

Because the Virtual Canvas consists of just a size, the resulting image will be that size, but have no virtual canvas offset, as such you do not need to worry about any offsets present in the final image.

This use of the virtual canvas to define the canvas on which to overlay the image means you can use it to add a surrounding border to an image. For example here I set the an image's size and virtual offset to 'pad out' an image to a specific size.

convert medical.gif -set page 64x64+20+20 \ -background SkyBlue -flatten flatten_padding.gif

Of course there are better ways to Pad Out an Image so that IM automatically centers the image in the larger area.

Strangely the exact same handling can be used to 'clip' or Crop an image to a virtual canvas that is smaller than the original image. In this case however you want to use a negative offset on the image, relative to its virtual canvas which is fixed to the virtual canvas origin, by its defination. convert logo: -set page 100x100-190-60 -flatten flatten_crop.gif

Of course a Viewport Crop would also do this better, without the extra processing of canvas generation and overlaying that "-flatten" also does. It also will not 'expand' the image itself to cover the whole viewport if the image was only particilly contained in that viewing window.

The most common use of the "-flatten" operator is to set convert a background transparency into a specific color. That is overlay a single image on a background color of the same size as the original image. For example, lets add a colored background to the "number pad" we created above. convert append_array.gif -background LimeGreen -flatten flatten_bgnd.gif

Technically we could have also used "-mosaic" to set a background color, but "-flatten" is the more correct solution as it applies the canvas page information correctly.

If you are only wanting to replace the transparent background of multiple images, then you can use a zero width "-border" instead. This is not a "-layers" type of operator so does overlay multiple images into a single image, but will 'flatten' each individual image separatally. See Border Examples for details. convert append_array.gif -bordercolor Gold -border 0 border_bgnd.gif

As of IM v6.3.6-2 the "-flatten" operator is only an alias for a "-layers 'flatten'". Thus the "-flatten" option can be regarded as a short cut for the "-layers" method of the same name.

---

Canvas Expanding Mosaics

While "-flatten" can be regarded as the main 'work horse' of image layering techniques. The "-mosaic" operator is more like a self-expanding version.

Rather than only creating an initial canvas basied on just the canvas size of the inital image, "-mosaic" operator creates a canvas which is large enough to hold all the images.

For example here I don't even set an appropiate Virtual Canvas, however the "-mosaic" operator will work out how big such a canvas needs to be to hold all the image layers.

convert -page +5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -mosaic mosaic.gif

Note that the canvas is still sized from the 'origin' or 0,0 pixel. This is an important point of relation between "-mosaic" and "-flatten", and ensures the resulting image never has a virtual canvas offset.

Also note that the canvas will only expand in the positive directions (the bottom or right edges). As such "-mosaic" will still clip images with negative offsets...

convert -page -5-10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -mosaic mosaic_clip.gif

As on IM v6.3.6-2 the "-mosaic" operator is only an alias for a "-layers 'mosaic'". Thus the "-mosaic" option can be regarded as a short cut for the "-layers" method of the same name.

---

Layer Merging

The "-layers" method 'merge' is also very simular to the previous operators, and was added with IM v6.3.6-2. It only creates an image just large enough to hold all the given images at there respective offsets, but will not clip images with negative offsets.

Basically it makes a new virtual canvas layer of all the current existing layers, without any extra space. It also sets an virtual offset for the newly merged layer image, so the image remains correctly positioned, even if that means giving it a negative offset.

For example the first example of mosaic above will come out as...

convert -page +5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -layers merge +repage layers_merge.gif

While any image with a negative offset will not be clipped, but will also be preserved.

convert -page -5-10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background dodgerblue -layers merge +repage layers_merge_2.gif

Note that I used of the "+repage" operator in the above examples to remove the virtual canvas offset that would have been generated to correctly position the layer in the virtual image space. I did this as web browsers often have trouble with image offsets unless part of a GIF animation.

This method can also be used to add a background color to a image with transparency, but without 'filling out' the whole virtual canvas, or changing the images virtual 'page' settings. This can be important if the image is to be further processed afterward.

As a practical example of using these layering techniques, lets take a sequence of JPEG images, and in a loop, create Polariod Thumbnails. we can then read the size of these thumbnails and give each a virtual canvas position, before using "-layers" method 'merge', via a pipelined concatenated MIFF: file format technique.

This may seem a complex script but it really isn't, though windows, and PHP users may have some work to do to convert it. I have also expanded it and placed it in the Example Scripts area as "polariod_seires".

Basically the above example will let you programically generate just about any pattern or style of overlapping images on a virtual canvas. You do not need to calculate and generate an initial canvas, or trim it afterward, regardless of the number, size or the placement of the images. IM will do that work for you. You can even use negative positions for the images, (all the Y positions are negative in the above!).

All you need do is concentrate on the style and relative placement of the images on that canvas.

---

Coalesce, a Progressive Flatten

The "-coalesce" image operator, is really designed for converting GIF animations into a sequence of images. For examples see Coalescing Animations for details. However it is very closely associated with "-flatten", and has very useful effects for multi-layered images in this regard.

For example using "-coalesce" on a single image, will do exact the same job as using "-flatten" with a "-background" color of 'None' or 'Transparency'. That is it will 'fill out' the canvas of the image. convert -page 100x100+5+10 balloon.gif -coalesce coalesce_canvas.gif

When dealing with a image consisting on multiple layers, "-coalesce" can be used to generate a 'Progressive Flattening' of the image. But to do this we need to take a few precautions, to disable the 'GIF animation' effect of the operator.

In the above we "-set" all the "-dispose" settings to 'None'. This effectively tells "-coalesce" to just overlay each frame on top the results of the previous overlays.

The result is the first image is just a 'fill out' of the images canvas, with a transparency background. The next image is the previous with that layer overlaid. and so on. A 'progressive' flatten of the image sequence.

The last image in the sequence will thus be the same as if you did a normal "-flatten" with a transparent background.

You can get a completely different sort of effect if you had used a "-dispose" setting of 'Background'. In this case "-coalesce" will just 'fill out' the canvas of each image, as if they were completely separate images!

If you are actually wanting to also replace the transparent background of the multiple images, then you can add a zero width border instead of attempting to overlay each image onto a background one at a time.

Please note however that unlike "-mosaic" and "-flatten" or even "-border",   the "-coalesce" operator does not make use of the current "-compose" alpha composition setting. It only uses an 'Over' compose method, as this is what is hard coded internally.

Using different "-compose" methods with the more standard image layering operators is the subject of the next set of examples.

---

Compose Methods and Flatten

The three "-layers" methods 'flatten', 'mosaic', and 'merge', as well as the shortcut operators, "-flatten" and "-mosaic", all will make use of the "-compose" setting to determine the composition method used to overlay each image in sequence. As such you could think of these functions as a multi-image "-composite" operator with the ability to set an initial "-background" canvas color.

However using anything but the default Alpha Composition of 'Over' requires a some thought before applying or you will get unexpected results. You may also need to turn off the "-background" canvas by setting it to the transparent color 'none' to ensure it does not interfere.

For example lets place each successive image under the previous images using a 'DstOver'...

convert -page 100x100+5+10 balloon.gif -page +35+30 medical.gif \ -page +62+50 present.gif -page +10+55 shading.gif \ -background none -compose DstOver -flatten flatten_dstover.gif

Remeber the background was set to be transparent, otherwise you will only see the background canvas in the result as all the other images will have been placed 'under' this initial canvas! Of course that presents a way of 'blanking' an image with a particular color. For more details see Canvases Sized to an Existing Image.

Here is a more practical example. Rather than layering the images with the background canvas first, which awkward and un-natural in some image processing situations, you can just generate the images top-down or foreground to background order. convert rose: -repage +20+20 \ \( +clone -background black -shadow 60x3+5+5 \) \ granite: -background none -compose DstOver -layers merge \ layer_reversed.gif

As you can see the image processing for the above was simplier and cleaner than you normally would see with shadow generation, just by underlaying each image in sequence (with a transparent starting canvas)

Of course I could have just as easilly Reverse the Image Sequence instead.

The compose methods can also be used to produce some interesting effects. For example, if you draw three circles, then by overlaying them using the 'Xor' compose method, you get a unusual and complex looking symbol, for minimal effort.

convert -size 60x60 \ \( xc:none -fill blue -draw 'circle 21,39 24,57' \) \ \( xc:none -fill red -draw 'circle 39,39 36,57' \) \ \( xc:none -fill green -draw 'circle 30,21 30,3' \) \ -background none -compose Xor -flatten flatten_xor.png

---

Averaging Images Together

The "-average" image list operator will merge the current sequence of images together by averaging their values. However all images in the sequence being averaged together, must be the same size, or this operator will probably silently fail.

An alternative for averaging two images together is to use a "composite -blend 50%" image operation, which will work with two different sized images. See the example of Blend Two Images Together for more detail.

Matt Leigh, of the University of Arizona, reports that he has used "-average" to improve the resolution of microscope images. He takes multiple images of the same "target" then averages them all together to increase the signal/noise ratio of the results. He suggests others may also find it useful for this purpose.

As video sequences are notoriously noisy when you look at the individual frames, you can average a number of consecutive, but unchanging, frames together to produce produce much better result.

---

Created: 3 January 2004
Updated: 6 October 2007
Author: Anthony Thyssen, <A.Thyssen@griffith.edu.au>
Examples Generated with:
URL: http://www.imagemagick.org/Usage/layers/