This page describes the image composition methods that define how
two images are merged together during the many image operations that combine a
'source' (overlay) image with a 'destination' (background) image. For the
Command Line API the method is normally selected with the -compose setting, and then applied by
operators such as -composite,
-layers, -flatten, -mosaic, -draw, and many others.
Most of the alpha-blending operators, and a large number of the blend
(lighting) modes, follow the W3C SVG Compositing Specification, which extends the SVG 1.1 and
SVG 1.2 languages with the full set of Porter–Duff
alpha operators and blend modes. Where an operator is defined by that standard,
ImageMagick implements the same mathematical result, so the behaviour is
directly comparable to SVG, PDF, and most modern graphics libraries. You can
review the precise formulae in the SVG specification, or in the ImageMagick
"Compositing Images" usage
examples.
The description of composition uses abstract terminology in order to keep the
definitions precise, while avoiding constant values that are specific to a
particular build configuration. Each image pixel is represented by red, green,
and blue levels (which are equal for a gray pixel). The build-dependent value
QuantumRange is the maximum value that may be stored, per pixel, in
the red, green, or blue channels of the image. Each image pixel may also
optionally (if the image alpha/matte channel is enabled) have an associated
level of opacity, ranging from opaque to transparent,
which determines the influence of the pixel color when it is composited with
another image pixel. If the alpha channel is disabled, then all pixels in the
image are treated as opaque. The color of an opaque pixel is fully visible,
while the color of a fully transparent pixel is entirely absent (its color is
ignored).
By definition, raster images have a rectangular shape: all image rows are of
equal length, as are all image columns. By treating the alpha channel as a
visual "mask", the rectangular image may be given an arbitrary "shape", with the
alpha channel acting as a cookie-cutter for the image. This is done by setting
the pixels within the shape to be opaque, and the pixels outside the shape to be
transparent. Pixels on the boundary of the shape may lie between opaque and
transparent in order to provide antialiasing (visually smooth edges). The
descriptions of the composition operators use this concept of image "shape" to
make them easier to understand. While it is convenient to describe the operators
in terms of "shapes", they are by no means limited to mask-style operations,
since they are based on continuous floating-point mathematics rather than simple
boolean operations.
The compose method names are case-insensitive, and the '_' or
'-' separators are optional. As such the method
'Dst-Over' may equally be written as 'dst_over',
'DstOver', or 'dstover'. They all mean the same
thing.
Duff–Porter Alpha Composition Methods
The following alpha-blending (Duff–Porter) compose methods are
available. These are the twelve classical Porter–Duff operators, defined
by the SVG 1.2 Compositing standard, which merge two images purely
according to their transparency (alpha channel).
| Method |
Description |
| clear |
Both the color and the alpha of the destination are cleared. Neither the
source nor the destination is used as input (except for the
destination's size and other meta-data, which are always preserved).
The result is a fully transparent image. |
| src |
The source is copied to the destination. The destination is not used as
input; it is completely replaced, and any area not overlaid by the
source is cleared to transparency. |
| dst |
The destination is left untouched. The source image is completely
ignored. This is effectively a "no operation" for the color data,
useful mainly for testing or for building larger expressions. |
| src-over |
The source is composited over the destination. This is the default
alpha-blending compose method, used when the compose setting is neither
set on the command line nor recorded in the image meta-data. It is the
result most people expect when overlaying one image on another. |
| dst-over |
The destination is composited over the source, and the result replaces
the destination. In effect the source is placed under the
destination, so only the parts of the source not hidden by the
destination remain visible. This is ideal for adding backgrounds or
drop shadows without altering the destination's size. |
| src-in |
The part of the source lying inside of the destination shape replaces
the destination. Everything outside the overlap (including the original
destination) is cleared to transparency. |
| dst-in |
The part of the destination lying inside of the source shape replaces
the destination. Areas not overlaid are cleared. This is a convenient
way to use the source purely as an alpha mask for the destination. |
| src-out |
The part of the source lying outside of the destination shape replaces
the destination. The overlapping region and the original destination are
cleared to transparency. |
| dst-out |
The part of the destination lying outside of the source shape replaces
the destination. In other words, the source shape is "punched out" of
the destination, leaving a hole. |
| src-atop |
The part of the source lying inside of the destination shape is
composited onto the destination. The destination keeps its shape and
alpha, while the source colors sit on top within that shape. |
| dst-atop |
The part of the destination lying inside of the source shape is
composited over the source and replaces the destination. Areas not
overlaid are cleared. The result keeps the shape of the source but the
colors of the destination within it. |
| xor |
The part of the source that lies outside of the destination is combined
with the part of the destination that lies outside of the source. That
is, the result shows the source or the destination, but not where the
two overlap (which is cleared). |
Any of the 'Src-*' methods can also be specified without the
'Src-' prefix. For example the default compose method may be
specified as just 'Over', and similarly 'In',
'Out', and 'ATop' are shorthand for
'Src-In', 'Src-Out', and 'Src-ATop'.
Many of these compose methods will clear the part of the destination image
that was not overlaid by the source image. This is an intended part of that
method's definition. The methods that clear the un-overlaid area are
'Clear', 'Src', 'Src-In',
'Dst-In', 'Src-Out', and 'Dst-ATop'. You
can disable this behaviour by setting the special -define
'compose:outside-overlay' to a value of 'false', so
that only the overlaid region is modified.
On top of the above twelve Duff–Porter alpha-composition methods, one
special related method 'Copy' is provided. It is equivalent to
using 'Src' with the 'compose:outside-overlay' define
set to 'false', so as to modify only the overlaid area without
clearing the rest of the destination image.
For example, to overlay a centered label over the built-in rose image using
the default 'Over' method…
magick rose: label.png -gravity center -compose Over -composite result.png
Or, to place the overlay under the destination — handy for
adding a hard drop shadow without changing the image size…
magick label_white.png label_black.png -geometry +5+5 -compose Dst-Over -composite shadow.png
Mathematical Composition Methods
The following mathematical composition methods are also available. Rather
than blending by transparency, these combine the source and destination
color channels using a specific arithmetic or comparison formula. Several of
them (Multiply, Screen, Darken,
Lighten, Difference, and Exclusion) are
the "separable blend modes" defined by the SVG 1.2 Compositing standard,
and behave identically to their SVG, PDF, and Photoshop equivalents.
| Method |
Description |
| multiply |
The source is multiplied by the destination and replaces the
destination. The resultant color is always at least as dark as either
of the two constituent colors. Multiplying any color with black produces
black; multiplying any color with white leaves the original color
unchanged. |
| divide |
Works by dividing the pixel values of one input image by those of another, channel by channel. This produces specialized blending effects, often for normalization or highlighting contrasts. |
| screen |
The source and destination are complemented, then multiplied, and the
result is complemented again and replaces the destination. The resultant
color is always at least as light as either of the two constituent
colors. Screening any color with white produces white; screening any
color with black leaves the original color unchanged. It is the
mathematical opposite of 'Multiply'. |
| bumpmap |
The intensity (grayscale value) of the source is multiplied with the
destination color. Unlike 'Multiply', which multiplies each
channel by the matching source channel, 'Bumpmap' uses the
single luminance of the source to shade the destination, which makes it
well suited to applying an embossed or relief texture as a light/shadow
map. |
| divide-dst |
Performs a true mathematical division of the destination color by the
source color, channel by channel ( Dc / Sc ), and replaces
the destination. Where the two images are equal the result is white
(1.0). This is the standard 'Divide' operator, and is an
efficient built-in replacement for the equivalent (but slow) -fx "divide" expression. It is
widely used to flatten uneven lighting or remove a background gradient,
e.g. by dividing a scan by a heavily blurred copy of itself. |
| divide-src |
The reverse of 'Divide-Dst': divides the source color by
the destination color ( Sc / Dc ) and replaces the
destination. Choose 'Divide-Src' or
'Divide-Dst' depending on which image should be the
numerator. |
| plus |
The source is added to the destination and replaces the destination,
with the alpha channels also added. This operator is useful for
averaging, or for a controlled merger of two images, rather than a
direct overlay. Values that exceed QuantumRange are clamped
to white. |
add
(modulus-add) |
As per 'Plus', but any result that exceeds
QuantumRange "wraps around" using modulus arithmetic rather
than being clamped. Transparency data is treated as matte values, so any
transparent areas in either image remain transparent. Also available as
the explicit name 'Modulus-Add'. |
minus
(minus-dst) |
Subtracts the source color from the destination color
( Dc - Sc ), with negative results clamped to black. When
transparency is involved, the source opaque areas are subtracted from
the destination opaque areas. |
| minus-src |
The reverse of 'Minus-Dst': subtracts the destination color
from the source color ( Sc - Dc ), with negative results
clamped to black. |
subtract
(modulus-subtract) |
Subtracts the source color from the destination color, but any negative
result "wraps around" using modulus arithmetic rather than being clamped
to black. When transparency is involved, transparent areas are
subtracted, so only the opaque areas in the source remain opaque in the
destination image. Also available as 'Modulus-Subtract'. |
| difference |
Subtracts the darker of the two constituent colors from the lighter one,
giving the absolute difference between them. Compositing with white
inverts the destination color; compositing with black produces no
change. Identical destination and source colors produce black, which
makes this method a convenient way to visually compare two images. |
| exclusion |
Produces an effect similar to 'Difference', but lower in
contrast. Compositing with white inverts the destination color;
compositing with black produces no change. |
| darken |
Selects the darker of the destination and source colors, compared
channel by channel. The destination is replaced with the source only
where the source is darker; otherwise it is left unchanged. |
| lighten |
Selects the lighter of the destination and source colors, compared
channel by channel. The destination is replaced with the source only
where the source is lighter; otherwise it is left unchanged. |
| darken-intensity |
Like 'Darken', but the choice is made by comparing the
overall pixel intensity (luminance) rather than each channel
separately. Whichever whole pixel is darker is kept, preserving its hue
instead of mixing channels from both images. |
| lighten-intensity |
Like 'Lighten', but the choice is made by comparing the
overall pixel intensity (luminance) rather than each channel
separately. Whichever whole pixel is lighter is kept. |
| negate |
The "opposite" of 'Difference' mode. Note that it is not
simply 'Difference' inverted, because black and white
return the same result, but intermediate colors become brighter instead
of darker. |
| reflect |
Useful when adding shining objects or bright light zones to an image.
The formula is related to 'Color-Dodge', but the result is
generally not as bright, giving something between a dodge and a soft
light. |
| freeze |
Another variation of 'Reflect' mode, computed by inverting
the base and blend colors, applying the reflect formula, and inverting
the result again. It tends to deepen and intensify shadow regions. |
| stamp |
Similar in spirit to an "average" mode. It is helpful when applying
relief or bump-style textures to an image while retaining the
destination's mid-tones. |
| interpolate |
Combines aspects of 'Multiply' and 'Screen'
mode using a smooth cosine interpolation, producing a gentle S-curve.
It looks very similar to the constituent colors for very dark or very
bright values. |
Typically these methods use the default 'Over' alpha blending
when transparencies are involved, except for 'Plus' (and
'Add'), which use a 'Plus' alpha blending. This means
the alpha channels of both images are used only to ensure that any visible input
remains visible even in parts that are not overlaid, and that the color values
are weighted by the alpha of the input and output images. This 'Over'
alpha blending is also applied to the lighting composition methods below.
Use -define compose:sync=false and the above mathematical
compositions will no longer synchronise their action with the alpha channel.
Instead the math composition is applied on an individual channel basis, as
selected by the -channel setting;
this includes the alpha channel itself. This special usage allows you to perform
true mathematics on the image channels, without the alpha composition becoming
involved.
This define is not applied to the lighting composition methods (see below),
even though they are closely related to the mathematical composition
methods.
A classic use of 'Divide' is to flatten uneven lighting or
remove a background gradient by dividing an image by a heavily blurred copy of
itself. Note the parentheses, which limit the blur to just the cloned copy…
magick scan.png \( +clone -blur 0x20 \) -compose Divide_Src -composite flattened.png
Lighting Composition Methods
The following lighting composition methods (the "light", "dodge", and "burn"
blend modes) are also available. Many are the standard non-separable
blend modes described by the SVG 1.2 Compositing standard, and match the
equivalent modes found in SVG, PDF, and popular image editors.
| Method |
Description |
| linear-dodge |
Equivalent to 'Plus' in that the color channels are simply
added; however it does not add the alpha channel, but instead uses the
normal 'Over' alpha blending when transparencies are
involved. Produces an additive, brightening result. |
| linear-burn |
As 'Linear-Dodge', but also subtracts one (full white) from
the result, darkening the image. It is, in effect, an additive
counterpart to 'Screen'. |
| color-dodge |
Brightens the destination color to reflect the source color, by dividing
the destination by the inverse of the source. Compositing with black
produces no change, while brighter source colors progressively blow out
the destination toward white. |
| color-burn |
Darkens the destination color to reflect the source color, the inverse
operation to 'Color-Dodge'. Compositing with white produces
no change, while darker source colors progressively burn the destination
toward black. |
| overlay |
Multiplies or screens the colors, depending on the destination color.
Source colors overlay the destination while preserving its highlights
and shadows. The destination color is not replaced, but is mixed with
the source color to reflect the lightness or darkness of the
destination. This is 'Hard-Light' with the source and
destination roles swapped. |
| hard-light |
Multiplies or screens the colors, depending on the source color value.
If the source color is lighter than 0.5, the destination is lightened as
if screened; if the source color is darker than 0.5, the destination is
darkened as if multiplied. The degree of lightening or darkening is
proportional to the difference between the source color and 0.5. If the
source equals 0.5 the destination is unchanged. Compositing with pure
black or white produces black or white. |
| hard-mix |
Adds the source and destination color values and then thresholds the
result to pure black or pure white on each channel. This produces a
high-contrast, posterised image restricted to the primary and secondary
colors. |
| linear-light |
Like 'Hard-Light', but using 'Linear-Dodge'
and 'Linear-Burn' instead of screen and multiply. It
increases contrast noticeably, with a strong impact on the foreground's
tonal values. |
| soft-burn |
A combination of color-burn and inverse color-dodge modes, but much
smoother than either. The base image is lightened a little, while very
dark blend colors are "burned" in. |
| soft-dodge |
A combination of color-dodge and inverse color-burn modes, but much
smoother than either. The base image is darkened a little, while very
bright blend colors are "dodged" in. |
| soft-light |
Darkens or lightens the colors, depending on the source color value. If
the source color is lighter than 0.5, the destination is lightened; if
it is darker than 0.5, the destination is darkened, as if burned in. The
degree of change is proportional to the difference between the source
color and 0.5. If the source equals 0.5 the destination is unchanged.
Compositing with pure black or white produces a distinctly darker or
lighter area, but never pure black or white. This is the SVG 1.2
"soft-light" blend mode. |
| pegtop-light |
Almost equivalent to 'Soft-Light', but computed with a
single continuous mathematical formula rather than two conditionally
selected formulae. This avoids the subtle discontinuity that
'Soft-Light' can show at a source value of 0.5. |
| vivid-light |
A modified 'Linear-Light' (a combination of
'Color-Dodge' and 'Color-Burn') designed to
preserve very strong primary and secondary colors in the image. |
| pin-light |
Similar to 'Hard-Light', but using sharp linear shadings,
to simulate the effect of a strong "pinhole" light source. It replaces
colors based on how light or dark the source is, which can remove
mid-tone detail. |
These blend modes are selected the same way as any other method. For
instance, to blend a texture into a photo with 'Soft-Light'…
magick photo.png texture.png -compose Soft-Light -composite result.png
Channel-Copying and Color (HSL) Methods
These methods do not blend the two images arithmetically. Instead they either
transfer individual channels from the source to the destination, or transfer one
component of the HSL color model (hue, saturation, or luminosity). The four HSL
methods (Hue, Saturate, Luminize, and
Colorize) correspond to the non-separable color blend modes of the
SVG 1.2 Compositing standard.
| Method |
Description |
| copy |
Equivalent to the Duff–Porter 'Src' composition
method, but without clearing the parts of the destination image
that are not overlaid. Only the overlaid area is replaced. |
| copy-<channel> |
Copies the specified channel (Red, Green,
Blue, Cyan, Magenta,
Yellow, Black, or Alpha) from the
source image into the same channel of the destination image, leaving the
other channels untouched. If the requested channel does not exist in the
source image (which can only happen for 'Copy-Alpha' or
'Copy-Black'), then the source is assumed to be a grayscale
image whose intensity supplies the values to be copied.
'Copy-Alpha' (formerly 'Copy-Opacity') is the
classic way to apply an explicit transparency mask to an image. |
| hue |
Replaces the hue of the destination with the hue of the source, while
keeping the destination's saturation and luminosity. |
| saturate |
Replaces the saturation of the destination with the saturation of the
source, while keeping the destination's hue and luminosity. |
| luminize |
Replaces the luminosity (brightness) of the destination with that of the
source, while keeping the destination's hue and saturation. |
| colorize |
Replaces the hue and saturation of the destination with those of the
source, while keeping the destination's luminosity. It is the exact
complement of 'Luminize' and is ideal for tinting a
grayscale image with a color. |
For example, to tint a grayscale portrait with a solid color using
'Colorize', which keeps the destination's luminosity but takes the
hue and saturation from the source…
magick portrait.png xc:steelblue -compose Colorize -composite tinted.png
Other Special-Purpose Methods
Also included are these special-purpose compose methods:
| Method |
Description |
| no |
A true "no operation". Used internally, and when layering images, to
indicate that no composition should be performed. The destination is
returned unchanged. |
| change-mask |
Replaces any destination pixel that is similar to the corresponding
source pixel (as defined by the current -fuzz factor) with transparency.
This is useful for producing a minimal "difference" overlay, such as when
optimising an animation. |
| stereo |
Creates a stereo anaglyph by taking the red channel from the source
image and the green and blue channels from the destination image, so the
combined result can be viewed with red/cyan 3D glasses. |
Composition Methods That Take Arguments
On top of the methods above are a few special ones that not only require the
two images being merged, but also take some extra numerical arguments, which are
tabled below.
In the "composite" command these composition methods are usually
selected using dedicated options that carry the arguments they need. Those
option names are usually—but not always—the same as the compose
'method' they use, and they replace the normal -compose setting. For example…
magick composite ... -blend 50x50 ...
The "magick" command can pass these extra arguments to its -composite operator using the
special -define attribute
compose:args. This means you can make use of these augmented -compose methods, though the argument
and the method must each be set separately. For example…
magick ... -compose blend -define compose:args=50,50 -composite ...
The following is a table of these special 'argumented' compose methods, with
a brief summary of what they do. For more detail see the equivalent
"composite" command option.
| Method |
Description |
| dissolve |
Arguments:
src_percent[xdst_percent]
Equivalent to "composite" -dissolve.
Dissolves the 'source' image by the percentage given before overlaying it
'over' the 'destination' image. If src_percent is greater than
100, it starts dissolving the destination image as well, so the
destination becomes fully transparent at a value of 200. If
both percentages are given, each image is dissolved to the percentage
given.
|
| blend |
Arguments:
src_percent[xdst_percent]
Equivalent to "composite" -blend.
Averages the images together ('plus') according to the percentages given and
each pixel's transparency. If only a single percentage is given, it sets
the weight of the 'source' image, while the 'destination' image is
weighted by the exact opposite amount. That is, -blend 30
merges 30% of the source with 70% of the destination, and is therefore
equivalent to -blend 30x70.
|
| mathematics |
Arguments: A, B, C, D
Not available in "composite" at this time.
Merges the source and destination images according to the formula
A*Sc*Dc + B*Sc + C*Dc + D
where Sc and Dc are the source and destination
color values. This can generate a custom composition method that would
otherwise need the slow -fx DIY
image operator. For example, setting A=1 with the other
coefficients zero reproduces 'Multiply'.
|
| modulate |
Arguments:
brightness[xsaturation]
Equivalent to "composite" -watermark.
Takes a grayscale image (with an alpha mask) and modifies the destination
image's brightness according to the source image's grayscale value and
the brightness percentage. The destination's color saturation
is scaled directly by the saturation percentage, which
defaults to 100 percent (no color change).
|
| displace |
Arguments:
X-scale[xY-scale][!][%]
Equivalent to "composite" -displace.
With this method, the 'overlay' image (and optionally the 'mask' image) is
used as a relative displacement map, which shifts the lookup of the
destination pixel that is seen at each point of the overlaid area. It is
much like a 'lens' that distorts the background image behind it.
The X-scale is modulated by the red channel of the overlay image, while
the Y-scale is modulated by the green channel (if a mask image is given,
it is rolled into the green channel of the overlay). This separation lets
you modulate the X and Y lookups independently, allowing 2-dimensional
displacements rather than the 1-dimensional vectored displacement of a
single grayscale image.
If the overlay image contains transparency, it is used as a mask on the
result to remove 'invalid' pixels.
The '%' flag makes the displacement scale relative to the
size of the overlay image (100% = half the width/height of the image).
Using '!' switches the percentage arguments to refer to the
destination image size instead.
|
| distort |
Arguments:
X-scale[xY-scale[+X-center+Y-center]][!][%]
Not available in "composite" at this time.
Exactly as per 'Displace' (above), but using absolute
coordinates relative to the center of the overlay (or to the center
given). This lets you generate absolute distortion maps, where 'black'
looks up the left/top edge and 'white' looks up the bottom/right edge of
the destination image, according to the scale given.
The '!' flag not only switches the percentage scaling to use
the destination image, but also references the center offset against the
destination. This means the overlay can look up a completely different
region of the destination image.
|
| blur |
Arguments:
Width[xHeight[+Angle][+Angle2]]
Equivalent to "composite" -blur.
A variable-blur mapping composition method, where each pixel in the overlaid
region is replaced with an Elliptical Weighted Average (EWA), using an
ellipse (typically a circle) of the given sigma size, scaled according
to the overlay (source) grayscale mapping.
As with 'Displace' and 'Distort', the red
channel modulates the width of the ellipse while the green channel
modulates its height. If a single Angle value is given, the ellipse is
rotated by that angle.
Normally the blue channel of the mapping overlay is ignored. However if a
second angle is given, the blue channel is taken to define a variable
angle for the ellipse, ranging from the first angle to the second. This
lets you generate radial blurs, a rough approximation of rotational blur,
or any mix of the two.
|
| seamless-blend |
Arguments: max-iterationsxdistortion
Seamlessly inserts the overlay image onto the background image. This
operator requires a mask. Set the maximum number of iterations and the
target distortion when seamlessly blending a foreground object onto a
background. The distortion is the RMSE between each iteration; a good
starting point is 300x0.0001. Note that seamless blending
works most effectively when the HDRI feature is enabled.
|
| saliency-blend |
Arguments: max-iterationsxdistortion
Merges the overlay image with the background image such that whichever
image is most salient (has the most detail) at a given pixel is the one
that shows in the result. This operator requires a mask. Set the maximum
number of iterations and the target distortion as for
'Seamless-Blend'; a good starting point is
300x0.0001. Note that this works most effectively when the
HDRI feature is enabled, and it is a little slower than seamless
blending.
|
To print a complete list of all the available compose operators supported by
your particular build, use -list
compose.
