>K  " Z 7 ImageMagick Image Compositing Utility9VL

 
>Contents


>Synopsis

Icombine [ options ... ] imagecomposite [ mask] combined

*Back to Contents
 
 

>Description

8combine combine images to create new images.

*Back to Contents
 
 

>Examples

9To combine an image of a cockatoo with a perch, use:


<combine cockatoo.miff perch.ras composite.miff

 

 
 
 


?To compute the difference between images in a series, use:


Kcombine -compose difference series.1 series.2 difference.miff

 

 
 
 


NTo combine an image of a cockatoo with a perch starting at location (100,150), use:


Scombine -geometry "+1"00"+1"50 cockatoo.miff perch.ras composite.miff

 

 
 
 


8To tile a logo across your image of a cockatoo, use


:convert +shade 30x60 cockatoo.miff mask.miff

\combine -compose bumpmap -tile logo.png cockatoo.miff mask.miff composite.miff

 

 
 
 


LTo combine a red, green, and blue color plane into a single composite image,try


Kcombine -compose ReplaceGreen red.png green.png red-green.png

Ocombine -compose ReplaceBlue red-green.png blue.png composite.png

 

 
 
 


*Back to Contents
 
 

>Options

FOptions are processed in command line order. Any option you specify onOthe command line remains in effect until it is explicitly changed by specifying.the option again with a different effect.
 
>-blend*value


*blend the two images a given percent.
 
>-cache.threshold

6megabytes of memory available to the pixel cache.

HImage pixels are stored in memory until 80 megabytes of memory have beenGconsumed. Subsequent pixel operations are cached on disk. Operations toOmemory are significantly faster but if your computer does not have a sufficientGamount of free memory you may want to adjust this threshold value.

 
>-colors*value

-preferred number of colors in the image.

GThe actual number of colors in the image may be less than your request,Hbut never more. Note, this is a color reduction option. Images with lessHunique colors than specified with this option will have any duplicate orUunused colors removed. Refer to quantize(9)for more details.

GNote, options -dither, -colorspace, and -treedepth*affect the color reduction algorithm.

>-colorspace*value

=the type of colorspace: GRAY, OHTA, RGB,Transparent, XYZ,HYCbCr, YIQ, YPbPr, YUV, or CMYK.

JColor reduction, by default, takes place in the RGB color space. EmpiricalNevidence suggests that distances in color spaces such as YUV or YIQ correspondLto perceptual color differences more closely than do distances in RGB space.HThese color spaces may give better results when color reducing an image.Refer to)quantize(9) for more details.

 

 K

The Transparent color space behaves uniquely in that it preserves,the matte channel of the image if it exists.G

The -colors or -monochrome option is required for thisoption to take effect.
>-comment+string


&annotate an image with a comment.

GBy default, each image is commented with its file name. Use this optionIto assign a specific comment to the image. Optionally you can include theJimage filename, type, width, height, or other image attribute by embeddingspecial format characters:
0
    %b   file size+    %d   directory4    %e   filename extention*    %f   filename(    %h   height0    %i   input filename'    %l   label(    %m   magick2    %n   number of scenes1    %o   output filename-    %p   page number/    %q   quantum depth.    %s   scene number1    %t   top of filename;    %u   unique temporary filename'    %w   width.    %x   x resolution.    %y   y resolution*    \\n   newline8    \\r   carriage return
For example,4
    -comment "%m:%f %wx%h"

Hproduces an image comment of MIFF:bird.miff 512x480 for anLimage titled bird.miff and whose width is 512 and height is 480.

FIf the first character of string is @, the image commentJis read from a file titled by the remaining characters in the string.

>-compose-operator

#the type of image composition.

PBy default, each of the composite image pixels are replaced by the correspondingFimage tile pixel. You can choose an alternate composite operation. How.each operator behaves is described below.

 
>over

:The result will be the union of the two image shapes, with composite?image obscuring image in the region of overlap.

>in

?The result is simply composite image cut by the shape of image.BNone of the image data of image will be in the result.

>out

?The resulting image is composite image with the shape of image cut out.

>atop

8The result is the same shape as image image, withcomposite imageHobscuring image where the image shapes overlap. Note this differs'from over because the portion ofcomposite image outsideimage's)shape does not appear in the result.

>xor

AThe result is the image data from both composite image and imageJthat is outside the overlap region. The overlap region will be blank.

>plus

GThe result is just the sum of the image data. Output values are croppedOto 255 (no overflow). This operation is independent of the matte channels.

>minus

KThe result of composite image - image, with underflow croppedGto zero. The matte channel is ignored (set to 255, full coverage).

>add

KThe result of composite image + image, with overflow wrappingaround (mod 256).

>subtract

LThe result of composite image - image, with underflow wrappingIaround (mod 256). The add and subtract operators can3be used to perform reversible transformations.

>difference

HThe result of abs(composite image - image). This is useful+for comparing two very similar images.

>bumpmap

7The result of image shaded by image.

>replace

1The resulting image is image replaced withcomposite image.+Here the matte information is ignored.

 

 
 
 



HThe image compositor requires a matte, or alpha channel in the image forKsome operations. This extra channel usually defines a mask which representsGa sort of a cookie-cutter for the image. This is the case when matte isJ255 (full coverage) for pixels inside the shape, zero outside, and betweenJzero and 255 on the boundary. For certain operations, if image doesInot have a matte channel, it is initialized with 0 for any pixel matchingAin color to pixel location (0,0), otherwise 255 (to work properlyborderwidthmust be 0).

>-compress)type

Dthe type of image compression: None, BZip, Fax,Group4, JPEG,7LZW, RunlengthEncoded or Zip.

MSpecify +compress to store the binary image in an uncompressed format.EThe default is the compression type of the specified image file.

>-densityB<width>x<height>

?vertical and horizontal resolution in pixels of the image.

MThis option specifies an image density when decoding a Postscript or PortableFDocument page. The default is 72 pixels per inch in the horizontal andIvertical direction. This option is used in concert with -page

>-displace<horizontalCscale>x<vertical scale>

9shift image pixels as defined by a displacement map.

GWith this option, composite image is used as a displacement map.GBlack, within the displacement map, is a maximum positive displacement.HWhite is a maximum negative displacement and middle gray is neutral. TheQdisplacement is scaled to determine the pixel shift. By default, the displacementGapplies in both the horizontal and vertical directions. However, if youspecifyDmask, composite image is the horizontal X displacementand-mask the vertical Y displacement.

>-displayHhost:display[.screen]

8specifies the X server to contact; see X(1).

>-dispose+method

GIF disposal method.

Here are the valid methods:
<
  0     No disposal specified.c  1     Do not dispose between frames.      S  2     Overwrite frame with background color from header.E  3     Overwrite with previous frame.

>-dither

8apply Floyd/Steinberg error diffusion to the image.

LThe basic strategy of dithering is to trade intensity resolution for spatialFresolution by averaging the intensities of several neighboring pixels.FImages which suffer from severe contouring when reducing colors can beimproved with this option.

KThe -colors or -monochrome option is required for this optionto take effect.

NUse +dither to render Postscript without text or graphic aliasing.

>-font)name

JThis option specifies the font to be used for displaying normal text.

IIf the font is a fully qualified X server font name, the font is obtainedfrom an X server (e.g.;-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*).GTo use a TrueType font, precede the TrueType filename with a @(e.g.@@times.ttf). Otherwise, specify a Postscript font (e.g.helvetica).

>-geometry"<width>x<height>{+-}<xIoffset>{+-}<y offset>{%}{!}{<}{>}

'the width and height of the image.

GBy default, the width and height are maximum values. That is, the imageMis expanded or contracted to fit the width and height value while maintainingJthe aspect ratio of the image. Append an exclamation point to the geometryHto force the image size to exactly the size you specify. For example, ifKyou specify 640x480! the image width is set to 640 pixels and heightIto 480. If only one factor is specified, both the width and height assumethe value.

7To specify a percentage width or height instead, append%. The imageJsize is multiplied by the width and height percentages to obtain the finalGimage dimensions. To increase the size of an image, use a value greaterHthan 100 (e.g. 125%). To decrease an image's size, use a percentage lessthan 100.

2Use > to change the dimensions of the imageonly if its sizeMexceeds the geometry specification. < resizes the image onlyGif its dimensions is less than the geometry specification. For example,Gif you specify 640x480> and the image size is 512x512, the imageGsize does not change. However, if the image is 1024x1024, it is resizedto 640x480.

WBy default the images are combined relative to the image gravity (see -gravity).JUse <x offset> and <y offset> to specify1a particular location to combine the images.

>-gravity)type

Pdirection image gravitates to within the composite: NorthWest, North, NorthEast,KWest, Center, East, SouthWest, South, SouthEast. See X(1) for details aboutthe gravity specification.

IThe direction you choose specifies where to position the image within theLcomposite. For example Center gravity forces the image to be centeredMwithin the composite. By default, the image gravity is NorthWest.

>-interlace)type

Gthe type of interlacing scheme: None, Line, Plane,5or Partition. The default is None.

KThis option is used to specify the type of interlacing scheme for raw imageLformats such as RGB or YUV. None means do not interlacef(RGBRGBRGBRGBRGBRGB...), Line uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...),Fand Plane uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).PartitionGis like plane except the different planes are saved to individual files*(e.g. image.R, image.G, and image.B).

FUse Line, or Plane to create an interlaced GIF orprogressiveJPEG image.

>-label)name

assign a label to an image.

GUse this option to assign a specific label to the image. Optionally youMcan include the image filename, type, width, height, or other image attributeLby embedding special format character. See -comment for details.

For example,
2
    -label "%m:%f %wx%h"

Fproduces an image label of MIFF:bird.miff 512x480 for anLimage titled bird.miff and whose width is 512 and height is 480.

GIf the first character of string is @, the image label isGread from a file titled by the remaining characters in the string.

IWhen converting to Postscript, use this option to specify a header stringto print above the image.

>-matte

Mstore matte channel if the image has one otherwise create an opaque one.

>-monochrome

,transform the image to black and white.

>-negate

Freplace every pixel with its complementary color (white becomes black, yellow becomes blue, etc.).

PThe red, green, and blue intensities of an image are negated. Use +negate6to only negate the grayscale pixels of the image.

>-page"<width>x<height>{+-}<xIoffset>{+-}<y offset>{%}{!}{<}{>}

*size and location of an image canvas.

0Use this option to specify the dimensions of thePostScript pageGin dots per inch or a TEXT page in pixels. The choices for a Postscriptpage are:
t
       11x17         792  1224 |       Ledger       1224   792    i       Legal         612  1008i       Letter        612   792P       LetterSmall   612   792d       ArchE        2592  3456d       ArchD        1728  2592d       ArchC        1296  1728i       ArchB         864  1296n       ArchA         648   864s       A0           2380  3368s       A1           1684  2380s       A2           1190  1684x       A3            842  1190}       A4            595   842d       A4Small       595   842}       A5            421   595}       A6            297   421}       A7            210   297}       A8            148   210}       A9            105   148}       A10            74   105s       B0           2836  4008s       B1           2004  2836s       B2           1418  2004s       B3           1002  1418x       B4            709  1002}       B5            501   709s       C0           2600  3677s       C1           1837  2600s       C2           1298  1837x       C3            918  1298}       C4            649   918}       C5            459   649}       C6            323   459y       Flsa          612   936 s       Flse          612   936[       HalfLetter    396   612

HFor convenience you can specify the page size by media (e.g. A4, Ledger,0etc.). Otherwise, -page behaves much like-geometry (e.g. -pageletter+43+43>).

FTo position a GIF image, use -page{+-}<x offset>{+-}<y)offset> (e.g. -page "+1"00+200).

OFor a Postscript page, the image is sized as in -geometry and positioneddrelative to the lower left hand corner of the page by {+-}<xoffset>{+-}<yGoffset>. Use -page 612x792>, for example, to center theHimage within the page. If the image size exceeds the Postscript page, it is reduced to fit the page.

=The default page dimensions for a TEXT image is 612x792.

9This option is used in concert with -density.

>-quality*value

%JPEG/MIFF/PNG compression level.

JFor the JPEG image format, quality is 0 (worst) to 100 (best). The defaultquality is 75.

NQuality for the MIFF and PNG image format sets the amount of image compressionI(quality / 10) and filter-type (quality % 10). Compression quality valuesNrange from 0 (worst) to 100 (best). If filter-type is 4 or less, the specified+filter-type is used for all scanlines:

    0: none    1: sub    2: up    3: average!    4: Paeth

GIf filter-type is 5, adaptive filtering is used when quality is greaterGthan 50 and the image does not have a color map, otherwise no filtering is used.

ZIf filter-type is 6 or more, adaptive filtering with minimum-sum-of-absolute-values is used.

JThe default is quality is 75. Which means nearly the best compression withadaptive filtering.

OFor further information, see the PNGspecification.

>-scene*value

image scene number.

>-size[<width>{%}x<height>{%}{+offset}{!}

#width and height of the image.

NUse this option to specify the width and height of raw images whose dimensionsHare unknown such as GRAY, RGB, or CMYK. In additionGto width and height, use -size to skip any header information inHthe image or tell the number of colors in a MAP image file, (e.g.-size 640x512+256).

>-stegano

$hide watermark within an image.

FUse an offset to start the image hiding some number of pixels from theJbeginning of the image. Note this offset and the image size. You will needFthis information to recover the steganographic image (e.g. display.-size 320x256+35 stegano:image.png).

>-stereo

3combine two image to create a stereo anaglyph.

JThe left side of the stereo pair is saved as the red channel of the outputLimage. The right sife is saved as the green channel. Red-blue stereo glasses4are required to properly view the stereo image.

>-tile

-repeat composite operation across image.

>-treedepth*value

ONormally, this integer value is zero or one. A zero or one tells combineGto choose an optimal tree depth for the color reduction algorithm.

GAn optimal depth generally allows the best representation of the sourceJimage with the fastest computational speed and the least amount of memory.FHowever, the default depth is inappropriate for some images. To assureGthe best representation, try values between 2 and 8 for this parameter.Refer to)quantize(9) for more details.

JThe -colors option is required for this option to take effect.

>-verbose

0print detailed information about the image.

KThis information is printed: image scene number; image name; combined imageMname; image size; the image class (DirectClass or PseudoClass);Hthe total number of unique colors; and the number of seconds to read andcombine the image.


JBy default, the image format is determined by its magic number. To specifyIa particular image format, precede the filename with an image format nameLand a colon (i.e. ps:image) or specify the image type as the filename suffixN(i.e. image.ps). See convert(1) for a list of valid image formats.

FWhen you specify X as your image type, the filename has special1meaning. It specifies an X window by id, name, orroot. If no filenameIis specified, the window is selected by clicking the mouse in the desired window.

-Specify image as - for standard input,combined as - forKstandard output. If image has the extension .Z or .gz,the file is uncompressed with0uncompress or gunzip respectively.FIf combined has the extension .Z or .gz, the fileJsize is compressed using with compress or gzip respectively.GFinally, precede the image file name with | to pipe to or from a system command.

GUse an optional index enclosed in brackets after a file name to specifyIa desired subimage of a multi-resolution image format like Photo CD (e.g.Nimg0001.pcd[4]) or a range for MPEG images (e.g. video.mpg[50-75]). A subimageGspecification can be disjoint (e.g. image.tiff[2,7,4]). For raw images,Vspecify a subimage with a geometry (e.g. -size 640x512 image.rgb[320x256+50+50]).

 

 H

The optional mask can be used to provide matte information forcompositeKwhen it has none or if you want a different mask. A mask image is typicallyOgrayscale and the same size as composite. If the image is not grayscale,Fit is converted to grayscale and the resulting intensities are used asmatte information.

HIf combined already exists, you will be prompted as to whether itshould be overwritten.

*Back to Contents
 
 

>Environment
 
>DISPLAY

9To get the default host, display number, and screen.


*Back to Contents
 
 

>Authors

jJohn Cristy, magick@wizards.dupont.comE.I.5du Pont de Nemours and Company Incorporated.

*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.

*Back to Contents




Home PageImage3manipulation software that works like magic.