compose.html 26.6 KB
Newer Older
Cristy's avatar
Cristy committed
1 2 3 4




cristy's avatar
cristy committed
5
<!DOCTYPE html>
cristy's avatar
cristy committed
6
<html lang="en">
cristy's avatar
cristy committed
7
<head>
Cristy's avatar
Cristy committed
8 9
  <meta charset="utf-8"  />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"  />
Cristy's avatar
Cristy committed
10
  <title>Alpha Compositing @ ImageMagick</title>
Cristy's avatar
Cristy committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
  <meta name="application-name" content="ImageMagick" />
  <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves." />
  <meta name="application-url" content="https://www.imagemagick.org" />
  <meta name="generator" content="PHP" />
  <meta name="keywords" content="alpha, compositing, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert" />
  <meta name="rating" content="GENERAL" />
  <meta name="robots" content="INDEX, FOLLOW" />
  <meta name="generator" content="ImageMagick Studio LLC" />
  <meta name="author" content="ImageMagick Studio LLC" />
  <meta name="revisit-after" content="2 DAYS" />
  <meta name="resource-type" content="document" />
  <meta name="copyright" content="Copyright (c) 1999-2017 ImageMagick Studio LLC" />
  <meta name="distribution" content="Global" />
  <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
  <link href="compose.html" rel="canonical" />
  <link href="../images/wand.png" rel="icon" />
  <link href="../images/wand.ico" rel="shortcut icon" />
  <link href="assets/magick.css" rel="stylesheet" />
cristy's avatar
cristy committed
31
</head>
cristy's avatar
cristy committed
32
<body>
Cristy's avatar
...  
Cristy committed
33 34
  <header>
  <nav class="navbar navbar-expand-md navbar-dark bg-dark fixed-top">
Cristy's avatar
...  
Cristy committed
35
    <a class="navbar-brand" href="../"><img class="d-block" id="logo" name="ImageMagick" alt="ImageMagick" width="32" height="32" src="../images/wand.ico"/></a>
Cristy's avatar
...  
Cristy committed
36 37 38 39 40 41 42
    <button class="navbar-toggler collapsed" type="button" data-toggle="collapse" data-target="#navbarsExampleDefault" aria-controls="navbarsExampleDefault" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
    </button>

    <div class="navbar-collapse collapse" id="navbarsExampleDefault" style="">
    <ul class="navbar-nav mr-auto">
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
43
        <a class="nav-link" href="../index.html">Home <span class="sr-only">(current)</span></a>
Cristy's avatar
...  
Cristy committed
44 45
      </li>
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
46
        <a class="nav-link" href="../www/download.html">Download</a>
Cristy's avatar
...  
Cristy committed
47 48
      </li>
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
49
        <a class="nav-link" href="../www/command-line-tools.html">Tools</a>
Cristy's avatar
...  
Cristy committed
50 51
      </li>
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
52
        <a class="nav-link" href="../www/command-line-processing.html">Command-line</a>
Cristy's avatar
...  
Cristy committed
53 54
      </li>
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
55
        <a class="nav-link" href="../www/resources.html">Resources</a>
Cristy's avatar
...  
Cristy committed
56 57
      </li>
      <li class="nav-item ">
Cristy's avatar
...  
Cristy committed
58
        <a class="nav-link" href="../www/develop.html">Develop</a>
Cristy's avatar
...  
Cristy committed
59 60
      </li>
      <li class="nav-item">
Cristy's avatar
...  
Cristy committed
61
        <a class="nav-link" target="_blank" href="https://www.imagemagick.org/discourse-server/">Community</a>
Cristy's avatar
...  
Cristy committed
62 63
      </li>
    </ul>
Cristy's avatar
...  
Cristy committed
64
    <form class="form-inline my-2 my-lg-0" action="https://www.imagemagick.org/script/search.php">
Cristy's avatar
Cristy committed
65
      <input class="form-control mr-sm-2" type="text" name="q" placeholder="Search" aria-label="Search">
Cristy's avatar
...  
Cristy committed
66
      <button class="btn btn-outline-success my-2 my-sm-0" type="submit" name="sa">Search</button>
Cristy's avatar
...  
Cristy committed
67 68 69
    </form>
    </div>
  </nav>
Cristy's avatar
...  
Cristy committed
70 71 72 73 74 75 76 77 78 79
  <div class="container">
   <script async="async" src="https://localhost/pagead/js/adsbygoogle.js"></script>    <ins class="adsbygoogle"
         style="display:block"
         data-ad-client="ca-pub-3129977114552745"
         data-ad-slot="6345125851"
         data-ad-format="auto"></ins>
    <script>
      (adsbygoogle = window.adsbygoogle || []).push({});
    </script>
  </div>
Cristy's avatar
...  
Cristy committed
80
  </header>
Cristy's avatar
...  
Cristy committed
81
  <main role="main" class="container">
Cristy's avatar
...  
Cristy committed
82
    <div class="magick-template">
cristy's avatar
cristy committed
83
<div class="magick-header">
cristy's avatar
cristy committed
84

cristy's avatar
cristy committed
85
<p class="lead magick-description">This page descibed the Image composition methods that is used to define how
cristy's avatar
cristy committed
86
two images should be merged together in various image operations.  For the
87
Command Line API it is typically set using the <a
Cristy's avatar
...  
Cristy committed
88
href="../www/command-line-options.html#compose" >-compose</a> setting option. </p>
cristy's avatar
cristy committed
89 90


cristy's avatar
cristy committed
91 92 93 94
<p>The description of composition uses abstract terminology in order to allow
the description to be more precise, while avoiding constant values which 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
cristy's avatar
cristy committed
95
build-dependent value <var>QuantumRange</var> is the maximum integral
cristy's avatar
cristy committed
96 97
value which may be stored, per pixel, in the red, green, or blue channels of
the image. Each image pixel may also optionally (if the image matte channel is
cristy's avatar
cristy committed
98 99
enabled) have an associated level of opacity, ranging from <var>opaque</var> to
<var>transparent</var>, which may be used to determine the influence of the pixel
cristy's avatar
cristy committed
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
color when compositing the pixel with another image pixel. If the image matte
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 transparent
pixel color is entirely absent (pixel color is ignored).</p>

<p>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 a "shape" by treating the
alpha channel as a cookie-cutter for the image. This is done by setting the
pixels within the shape to be opaque, with pixels outside the shape set as
transparent. Pixels on the boundary of the shape may be between opaque and
transparent in order to provide antialiasing (visually smooth edges). The
description of the composition operators use this concept of image "shape" in
order to make the description of the operators 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.</p>

<p>The following alpha blending (Duff-Porter) compose methods are available:</p>

Cristy's avatar
...  
Cristy committed
120
<table class="table table-sm table-striped">
cristy's avatar
cristy committed
121
  <tbody>
cristy's avatar
cristy committed
122
  <tr>
cristy's avatar
cristy committed
123 124 125 126
    <th align="left" style="width: 8%">Method</th>
    <th align="left">Description</th>
  </tr>

cristy's avatar
cristy committed
127 128 129
  <tr>
    <td>clear</td>
    <td>Both the color and the alpha of the destination are
cristy's avatar
cristy committed
130 131 132 133
        cleared. Neither the source nor the destination are used (except for
        destinations size and other meta-data which is always preserved.</td>
  </tr>

cristy's avatar
cristy committed
134 135 136
  <tr>
    <td>src</td>
    <td>The source is copied to the destination. The destination
cristy's avatar
cristy committed
137 138 139
        is not used as input, though it is cleared.</td>
  </tr>

cristy's avatar
cristy committed
140 141 142
  <tr>
    <td>dst</td>
    <td>The destination is left untouched. The source image is
cristy's avatar
cristy committed
143 144 145
        completely ignored.</td>
  </tr>

cristy's avatar
cristy committed
146 147 148
  <tr>
    <td>src-over</td>
    <td>The source is composited over the destination. this is
cristy's avatar
cristy committed
149 150 151 152
       the default alpha blending compose method, when neither the compose
       setting is set, nor is set in the image meta-data.</td>
  </tr>

cristy's avatar
cristy committed
153 154 155
  <tr>
    <td>dst-over</td>
    <td>The destination is composited over the source and the
cristy's avatar
cristy committed
156 157 158
        result replaces the destination.</td>
  </tr>

cristy's avatar
cristy committed
159 160 161
  <tr>
    <td>src-in</td>
    <td>The part of the source lying inside of the destination
cristy's avatar
cristy committed
162 163 164
        replaces the destination.</td>
  </tr>

cristy's avatar
cristy committed
165 166 167
  <tr>
    <td>dst-in</td>
    <td>The part of the destination lying inside of the source
cristy's avatar
cristy committed
168 169 170
        replaces the destination. Areas not overlaid are cleared.</td>
  </tr>

cristy's avatar
cristy committed
171 172 173
  <tr>
    <td>src-out</td>
    <td>The part of the source lying outside of the destination
cristy's avatar
cristy committed
174 175 176
        replaces the destination.</td>
  </tr>

cristy's avatar
cristy committed
177 178 179
  <tr>
    <td>dst-out</td>
    <td>The part of the destination lying outside of the source
cristy's avatar
cristy committed
180 181 182
        replaces the destination.</td>
  </tr>

cristy's avatar
cristy committed
183 184 185
  <tr>
    <td>src-atop</td>
    <td>The part of the source lying inside of the destination is
cristy's avatar
cristy committed
186 187 188
        composited onto the destination.</td>
  </tr>

cristy's avatar
cristy committed
189 190 191
  <tr>
    <td>dst-atop</td>
    <td>The part of the destination lying inside of the source is
cristy's avatar
cristy committed
192 193 194 195
        composited over the source and replaces the destination. Areas not
        overlaid are cleared. </td>
  </tr>

cristy's avatar
cristy committed
196 197 198
  <tr>
    <td>xor</td>
    <td>The part of the source that lies outside of the
cristy's avatar
cristy committed
199 200 201 202 203 204 205 206
        destination is combined with the part of the destination that lies
        outside of the source.  Source or Destination, but not both. </td>
  </tr>

  </tbody>
</table>

<p>Any of the 'Src-*' methods can also be specified without the 'Src-' part.
cristy's avatar
cristy committed
207 208 209 210
For example the default compose method can be specified as just 'Over'.</p>

<p>Many of these compose methods will clear the destination image which was
not overlaid by the source image.  This is to be expected as part of that
cristy's avatar
cristy committed
211
specific composition methods defintion. You can disable this by setting the
Cristy's avatar
...  
Cristy committed
212
special <a href="../www/command-line-options.html#define"
Cristy's avatar
Cristy committed
213
>-define</a> 'compose:outside-overlay' to a value of 'false' will turn off
Cristy's avatar
Cristy committed
214
this behavior. </p>
cristy's avatar
cristy committed
215

cristy's avatar
cristy committed
216
<p>On top of the above 12 Duff-Porter Alpha Composition methods, one special
cristy's avatar
cristy committed
217
related method '<code>Copy</code>' has been provided. This is equivalent to
Cristy's avatar
...  
Cristy committed
218
using the '<code>Src</code>'  with the special <a href="../www/command-line-options.html#define"
Cristy's avatar
Cristy committed
219
>-define</a> option '<code>compose:outside-overlay</code>' set to
cristy's avatar
cristy committed
220
'<code>false</code>', so as to only modify the overlaid area, without clearing
cristy's avatar
cristy committed
221
the rest of the image outside the overlaid area.  </p>
cristy's avatar
cristy committed
222

Cristy's avatar
Cristy committed
223
<p>The following mathematical composition methods are also available. </p>
cristy's avatar
cristy committed
224

Cristy's avatar
...  
Cristy committed
225
<table class="table table-sm table-striped">
cristy's avatar
cristy committed
226
  <tbody>
cristy's avatar
cristy committed
227
  <tr>
cristy's avatar
cristy committed
228 229 230 231
    <th align="left" style="width: 8%">Method</th>
    <th align="left">Description</th>
  </tr>

cristy's avatar
cristy committed
232 233 234
  <tr>
    <td>multiply</td>
    <td>The source is multiplied by the destination and replaces
cristy's avatar
cristy committed
235 236 237 238 239 240
        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.</td>
  </tr>

cristy's avatar
cristy committed
241 242 243
  <tr>
    <td>screen</td>
    <td>The source and destination are complemented and then
cristy's avatar
cristy committed
244 245 246 247 248 249
        multiplied and then replace 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.</td>
  </tr>

cristy's avatar
cristy committed
250 251 252
  <tr>
    <td>plus</td>
    <td>The source is added to the destination and replaces the
Cristy's avatar
Cristy committed
253
        destination. This operator is useful for averaging or a controlled
cristy's avatar
cristy committed
254 255 256
        merger of two images, rather than a direct overlay.</td>
  </tr>

cristy's avatar
cristy committed
257 258 259
  <tr>
    <td>add</td>
    <td>As per 'plus' but transparency data is treated as matte
cristy's avatar
cristy committed
260 261 262 263
        values. As such any transparent areas in either image remain
        transparent. </td>
  </tr>

cristy's avatar
cristy committed
264 265 266
  <tr>
    <td>minus</td>
    <td>Subtract the colors in the source image from the
cristy's avatar
cristy committed
267 268 269 270
        destination image. When transparency is involved, opaque areas is
        subtracted from any destination opaque areas. </td>
  </tr>

cristy's avatar
cristy committed
271 272 273
  <tr>
    <td>subtract</td>
    <td>Subtract the colors in the source image from the
cristy's avatar
cristy committed
274 275 276 277 278
        destination image. When transparency is involved transparent areas are
        subtracted, so only the opaque areas in the source remain opaque in
        the destination image. </td>
  </tr>

cristy's avatar
cristy committed
279 280 281
  <tr>
    <td>difference</td>
    <td>Subtracts the darker of the two constituent colors from
cristy's avatar
cristy committed
282 283 284 285
        the lighter. Painting with white inverts the destination color.
        Painting with black produces no change.</td>
  </tr>

cristy's avatar
cristy committed
286 287 288
  <tr>
    <td>exclusion</td>
    <td>Produces an effect similar to that of 'difference', but
cristy's avatar
cristy committed
289 290 291 292
        appears as lower contrast.  Painting with white inverts the
        destination color. Painting with black produces no change.</td>
  </tr>

cristy's avatar
cristy committed
293 294 295
  <tr>
    <td>darken</td>
    <td>Selects the darker of the destination and source colors.
cristy's avatar
cristy committed
296 297 298 299
        The destination is replaced with the source when the source is darker,
        otherwise it is left unchanged.</td>
  </tr>

cristy's avatar
cristy committed
300 301 302
  <tr>
    <td>lighten</td>
    <td>Selects the lighter of the destination and source colors.
cristy's avatar
cristy committed
303 304 305 306 307 308 309 310
        The destination is replaced with the source when the source is
        lighter, otherwise it is left unchanged. </td>
  </tr>

  </tbody>
</table>

<p>Typically these use the default 'Over' alpha blending when transparencies
cristy's avatar
cristy committed
311 312 313 314 315 316
are also involved, except for 'Plus' which uses a 'plus' alpha blending.  This
means the alpha channel  of both images will only be used to ensure that any
visible input remains visible even in parts not overlaid. It also means that
any values are weighted by the alpha channel of the input and output images.
This 'Over' alpha blending is also applied to the lighting composition methods
below. </p>
cristy's avatar
cristy committed
317

Cristy's avatar
...  
Cristy committed
318
<p> The math composition is applied on an individual channel basis as defined by the <a href="../www/command-line-options.html#channel" >-channel</a>.  This includes the alpha channel. This special usage allows you to perform true mathematics of the image channels, without alpha
Cristy's avatar
Cristy committed
319
composition effects, becoming involved. </p>
cristy's avatar
cristy committed
320 321 322

<p>The following lighting composition methods are also available. </p>

Cristy's avatar
...  
Cristy committed
323
<table class="table table-sm table-striped">
cristy's avatar
cristy committed
324
  <tbody>
cristy's avatar
cristy committed
325
  <tr>
cristy's avatar
cristy committed
326 327 328 329
    <th align="left" style="width: 8%">Method</th>
    <th align="left">Description</th>
  </tr>

cristy's avatar
cristy committed
330 331 332
  <tr>
    <td>linear-dodge</td>
    <td>This is equivalent to 'Plus' in that the color channels
cristy's avatar
cristy committed
333 334
        are simply added, however it does not 'Plus' the alpha channel, but
        uses the normal 'Over' alpha blending, which transparencies are
Cristy's avatar
...  
Cristy committed
335
        involved.  Produces a sort of additive multiply-like result.  </td>
cristy's avatar
cristy committed
336 337
  </tr>

cristy's avatar
cristy committed
338 339 340
  <tr>
    <td>linear-burn</td>
    <td>As 'Linear-Dodge', but also subtract one from the result.
Cristy's avatar
...  
Cristy committed
341
        Sort of a additive 'Screen' of the images. </td>
cristy's avatar
cristy committed
342 343
  </tr>

cristy's avatar
cristy committed
344 345 346
  <tr>
    <td>color-dodge</td>
    <td>Brightens the destination color to reflect the source
cristy's avatar
cristy committed
347 348 349
        color. Painting with black produces no change.</td>
  </tr>

cristy's avatar
cristy committed
350 351 352
  <tr>
    <td>color-burn</td>
    <td>Darkens the destination color to reflect the source
Cristy's avatar
...  
Cristy committed
353
        color.  Painting with white produces no change.  </td>
cristy's avatar
cristy committed
354 355
  </tr>

cristy's avatar
cristy committed
356 357 358
  <tr>
    <td>overlay</td>
    <td>Multiplies or screens the colors, dependent on the
cristy's avatar
cristy committed
359 360 361 362 363 364
        destination color. Source colors overlay the destination whilst
        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.</td>
  </tr>

cristy's avatar
cristy committed
365 366 367
  <tr>
    <td>hard-light</td>
    <td>Multiplies or screens the colors, dependent on the source
cristy's avatar
cristy committed
368 369 370 371 372 373 374 375 376 377
        color value. If the source color is lighter than 0.5, the destination
        is lightened as if it were screened. If the source color is darker
        than 0.5, the destination is darkened, as if it were multiplied. The
        degree of lightening or darkening is proportional to the difference
        between the source color and 0.5. If it is equal to 0.5 the
        destination is unchanged.  Painting with pure black or white produces
        black or white.</td>
  </tr>


cristy's avatar
cristy committed
378 379 380
  <tr>
    <td>linear-light</td>
    <td>Like 'Hard-Light' but using linear-dodge and linear-burn
cristy's avatar
cristy committed
381 382 383 384
        instead.  Increases contrast slightly with an impact on the
        foreground's tonal values.</td>
  </tr>

cristy's avatar
cristy committed
385 386 387
  <tr>
    <td>soft-light</td>
    <td>Darkens or lightens the colors, dependent on the source
cristy's avatar
cristy committed
388 389 390 391 392 393
        color value. If the source color is lighter than 0.5, the destination
        is lightened. If the source color is darker than 0.5, the destination
        is darkened, as if it were burned in. The degree of darkening or
        lightening is proportional to the difference between the source color
        and 0.5. If it is equal to 0.5, the destination is unchanged. Painting
        with pure black or white produces a distinctly darker or lighter area,
Cristy's avatar
...  
Cristy committed
394
        but does not result in pure black or white. </td>
cristy's avatar
cristy committed
395 396
  </tr>

cristy's avatar
cristy committed
397 398 399
  <tr>
    <td>pegtop-light</td>
    <td>Almost equivalent to 'Soft-Light', but using a
Cristy's avatar
Cristy committed
400
        continuous mathematical formula rather than two conditionally
Cristy's avatar
...  
Cristy committed
401
        selected formulae. </td>
cristy's avatar
cristy committed
402 403
  </tr>

cristy's avatar
cristy committed
404 405 406
  <tr>
    <td>vivid-light</td>
    <td>A modified 'Linear-Light' designed to preserve very stong
Cristy's avatar
...  
Cristy committed
407
        primary and secondary colors in the image.  </td>
cristy's avatar
cristy committed
408 409
  </tr>

cristy's avatar
cristy committed
410 411 412
  <tr>
    <td>pin-light</td>
    <td>Similar to 'Hard-Light', but using sharp linear shadings,
Cristy's avatar
...  
Cristy committed
413
        to simulate the effects of a strong 'pinhole' light source. </td>
cristy's avatar
cristy committed
414 415 416 417 418 419 420
  </tr>

  </tbody>
</table>

<p>Also included are these special purpose compose methods:</p>

Cristy's avatar
...  
Cristy committed
421
<table class="table table-sm table-striped">
cristy's avatar
cristy committed
422
  <tbody>
cristy's avatar
cristy committed
423
  <tr>
cristy's avatar
cristy committed
424 425 426 427
    <th align="left" style="width: 8%">Method</th>
    <th align="left">Description</th>
  </tr>

cristy's avatar
cristy committed
428 429 430
  <tr>
    <td>copy</td>
    <td>This is equivalent to the Duff-Porter composition method
cristy's avatar
cristy committed
431
        '<code>Src,</code>' but without clearing the parts of the destination
cristy's avatar
cristy committed
432 433 434
        image that is not overlaid.  </td>
    </tr>

cristy's avatar
cristy committed
435 436 437
  <tr>
    <td>copy-*</td>
    <td>Copy the specified channel (Red, Green, Blue, Cyan,
cristy's avatar
cristy committed
438 439 440
        Magenta, Yellow, Black, or Opacity) in the source image to the
        same channel in the destination image.  If the channel specified
        does not exist in the source image, (which can only happen for methods,
cristy's avatar
cristy committed
441
        '<code>copy-opacity</code>' or '<code>copy-black</code>') then it is
cristy's avatar
cristy committed
442
        assumed that the source image is a special grayscale channel image
cristy's avatar
cristy committed
443
        of the values that is to be copied. </td>
cristy's avatar
cristy committed
444 445
    </tr>

cristy's avatar
cristy committed
446 447 448
  <tr>
    <td>change-mask</td>
    <td>Replace any destination pixel that is the similar to the
Cristy's avatar
Cristy committed
449
    source images pixel (as defined by the current <a
Cristy's avatar
...  
Cristy committed
450
    href="../www/command-line-options.html#fuzz">-fuzz</a> factor), with transparency.
cristy's avatar
cristy committed
451
    </td>
cristy's avatar
cristy committed
452
  </tr>
Cristy's avatar
...  
Cristy committed
453 454 455 456 457

  <tr>
    <td>stereo</td>
    <td>create a stereo anaglyph</td>
  </tr>
cristy's avatar
cristy committed
458 459 460 461 462 463 464 465 466
  </tbody>
</table>

<p>On top of these composed methods are a few special ones that not only require
the two images that are being merged or overlaid, but have some extra numerical
arguments, which are tabled below. </p>

<p>In the "<code>composite</code>" command these composition methods are
selected using special options with the arguments needed. They are usually,
Cristy's avatar
Cristy committed
467
but not always, the same name as the composite 'method' they use, and replaces
Cristy's avatar
...  
Cristy committed
468
the normal use of the <a href="../www/command-line-options.html#compose" >-compose</a>
cristy's avatar
cristy committed
469
setting in the "<code>composite</code>" command.  For example... </p>
cristy's avatar
cristy committed
470

Cristy's avatar
...  
Cristy committed
471
<pre class="highlight"><code>composite ... -blend 50x50 ...
Cristy's avatar
...  
Cristy committed
472
</code></pre>
cristy's avatar
cristy committed
473

Cristy's avatar
...  
Cristy committed
474 475
<p>The "<code>magick</code>" command can accept these extra arguments to its <a href="../www/command-line-options.html#composite"
>-composite</a> operator, using the special <a href="../www/command-line-options.html#define">-define</a>
cristy's avatar
cristy committed
476
attribute of '<code class="arg">compose:args</code>'.  This means you can now
Cristy's avatar
...  
Cristy committed
477
make use of these special augmented <a href="../www/command-line-options.html#compose"
Cristy's avatar
Cristy committed
478
>-compose</a> methods, those the argument and the method both need to be set
cristy's avatar
cristy committed
479
separately.  For example... </p>
cristy's avatar
cristy committed
480

Cristy's avatar
...  
Cristy committed
481
<pre class="highlight"><code>convert ... -compose blend  -define compose:args=50,50 -composite ...
Cristy's avatar
...  
Cristy committed
482
</code></pre>
cristy's avatar
cristy committed
483

cristy's avatar
cristy committed
484 485 486 487
<p>The following is a table of these special 'argumented' compose methods,
with a brief summary of what they do. For more details see the equivalent
"composite" command option name.  </p>

Cristy's avatar
...  
Cristy committed
488
<table class="table table-sm table-striped">
cristy's avatar
cristy committed
489
  <tbody>
cristy's avatar
cristy committed
490
  <tr>
cristy's avatar
cristy committed
491 492 493 494
    <th align="left" style="width: 8%">Method</th>
    <th align="left">Description</th>
  </tr>

cristy's avatar
cristy committed
495 496 497 498
  <tr>
    <td>dissolve</td>
    <td>Arguments:
        <var>src_percent</var>[x<var>dst_percent</var>]
Cristy's avatar
...  
Cristy committed
499
    <br/>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#dissolve">-dissolve</a>
Cristy's avatar
Cristy committed
500
    <br/>Dissolve the 'source' image by the percentage given before overlaying
cristy's avatar
cristy committed
501
        'over' the 'destination' image. If <var>src_percent</var> is
cristy's avatar
cristy committed
502
        greater than 100, it starts dissolving the main image so it will
cristy's avatar
cristy committed
503
        become transparent at a value of '<code class="arg">200</code>'.  If
cristy's avatar
cristy committed
504 505 506 507 508
        both percentages are given, each image are dissolved to the
        percentages given.
    </td>
  </tr>

cristy's avatar
cristy committed
509 510 511 512
  <tr>
    <td>blend</td>
    <td>Arguments:
        <var>src_percent</var>[x<var>dst_percent</var>]
Cristy's avatar
Cristy committed
513
    <br/>Equivalent to "<code>composite</code>" <a
Cristy's avatar
...  
Cristy committed
514
        href="../www/command-line-options.html#blend">-blend</a>
Cristy's avatar
Cristy committed
515
    <br/>Average the images together ('plus') according to the percentages
cristy's avatar
cristy committed
516 517 518
        given and each pixels transparency.  If only a single percentage value
        is given it sets the weight of the composite or 'source' image, while
        the background image is weighted by the exact opposite amount. That is
cristy's avatar
cristy committed
519 520 521
        a <code>-blend 30</code> merges 30% of the 'source' image with 70% of
        the 'destination' image.  Thus it is equivalent to <code>-blend
        30x70</code>.
cristy's avatar
cristy committed
522 523 524
    </td>
  </tr>

cristy's avatar
cristy committed
525 526 527
  <tr>
    <td>mathematics</td>
    <td>Arguments: <var>A, B, C, D</var>
Cristy's avatar
Cristy committed
528 529 530 531 532
    <br/>Not available in "<code>composite</code>" at this time.
    <br/>Merge the source and destination images according to the formula
    <br/>     <code>A*Sc*Dc + B*Sc + C*Dc + D</code>
    <br/>Can be used to generate a custom composition method that would
        otherwise need to be implemented using the slow <a
Cristy's avatar
...  
Cristy committed
533
        href="../www/command-line-options.html#fx">-fx</a> DIY image operator.
cristy's avatar
cristy committed
534 535 536
    </td>
  </tr>

cristy's avatar
cristy committed
537 538 539 540
  <tr>
    <td>modulate</td>
    <td>Arguments:
        <var>brightness</var>[x<var>saturation</var>]
Cristy's avatar
...  
Cristy committed
541
    <br/>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#watermark">-watermark</a>
Cristy's avatar
Cristy committed
542
    <br/>Take a grayscale image (with alpha mask) and modify the destination
cristy's avatar
cristy committed
543
        image's brightness according to watermark image's grayscale value and
cristy's avatar
cristy committed
544 545
        the <var>brightness</var> percentage.  The destinations
        color saturation attribute is just direct modified by the <var>saturation</var> percentage, which defaults to 100 percent
cristy's avatar
cristy committed
546 547 548 549 550
        (no color change).

    </td>
  </tr>

cristy's avatar
cristy committed
551 552 553 554
  <tr>
    <td>displace</td>
    <td>Arguments:
        <var>X-scale</var>[x<var>Y-scale</var>][!][%]
Cristy's avatar
...  
Cristy committed
555
    <br/>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#displace">-displace</a>
Cristy's avatar
Cristy committed
556
    <br/>With this option, the 'overlay' image, and optionally the 'mask'
cristy's avatar
cristy committed
557 558 559 560
        image, is used as a relative displacement map, which is used to
        displace the lookup of what part of the destination image is seen at
        each point of the overlaid area.  Much like the displacement map is a
        'lens' that distorts the original 'background' image behind it.
Cristy's avatar
Cristy committed
561
    <br/><br/>
cristy's avatar
cristy committed
562
        The X-scale is modulated by the 'red' channel of the overlay image
cristy's avatar
cristy committed
563 564 565
        while the Y-scale is modulated by the green channel, (the mask image
        if given is rolled into green channel of the overlay image. This
        separation allows you to modulate the X and Y lookup displacement
cristy's avatar
cristy committed
566
        separately allowing you to do 2-dimensional displacements, rather
Cristy's avatar
Cristy committed
567
        than 1-dimensional vectored displacements (using grayscale image).
Cristy's avatar
Cristy committed
568
    <br/><br/>
cristy's avatar
cristy committed
569 570
        If the overlay image contains transparency this is used as a mask
        of the resulting image to remove 'invalid' pixels.
Cristy's avatar
Cristy committed
571
    <br/><br/>
cristy's avatar
cristy committed
572 573 574
        The '%' flag makes the displacement scale relative to the size of the
        overlay image (100% = half width/height of image). Using '!' switches
        percentage arguments to refer to the destination image size instead.
Cristy's avatar
Cristy committed
575
    <br/><br/>
cristy's avatar
cristy committed
576 577 578
    </td>
  </tr>

cristy's avatar
cristy committed
579 580 581 582
  <tr>
    <td>distort</td>
    <td>Arguments:
        <var>X-scale</var>[x<var>Y-scale</var>[+<var>X-center</var>+<var>Y-center</var>]][!][%]
Cristy's avatar
Cristy committed
583 584
    <br/>Not available in "<code>composite</code>" at this time.
    <br/>Exactly as per 'Displace' (above), but using absolute coordinates,
cristy's avatar
cristy committed
585 586 587 588
        relative to the center of the overlay (or that given).  Basically
        allows you to generate absolute distortion maps where 'black' will
        look up the left/top edge, and 'white' looks up the bottom/right
        edge of the destination image, according to the scale given.
Cristy's avatar
Cristy committed
589
    <br/><br/>
cristy's avatar
cristy committed
590 591 592 593
        The '!' flag not only switches percentage scaling, to use the
        destination image, but also the image the center offset of the lookup.
        This means the overlay can lookup a completely different region of the
        destination image.
Cristy's avatar
Cristy committed
594
    <br/><br/>
cristy's avatar
cristy committed
595 596 597
    </td>
  </tr>

cristy's avatar
cristy committed
598 599 600 601
  <tr>
    <td>blur</td>
    <td>Arguments:
        <var>Width</var>[x<var>Height</var>[+<var>Angle</var>][+<var>Angle2</var>]]
Cristy's avatar
...  
Cristy committed
602
    <br/>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#blur-composite">-blur</a>
Cristy's avatar
Cristy committed
603
    <br/>A Variable Blur Mapping Composition method, where each pixel in the
cristy's avatar
cristy committed
604 605 606
        overlaid region is replaced with an Elliptical Weighted Average (EWA),
        with an ellipse (typically a circle) of the given sigma size, scaled
        according to overlay (source image) grayscale mapping.
Cristy's avatar
Cristy committed
607
    <br/><br/>
cristy's avatar
cristy committed
608 609
        As per 'Displace' and 'Distort', the red channel will modulate the
        width of the ellipse, while the green channel will modulate the height
cristy's avatar
cristy committed
610
        of the ellipse. If a single Angle value is given in the arguments,
Cristy's avatar
Cristy committed
611
        then the ellipse will then be rotated by the angle specified.
Cristy's avatar
Cristy committed
612
    <br/><br/>
cristy's avatar
cristy committed
613 614 615 616 617 618
        Normally the blue channel of the mapping overlay image is ignored.
        However if a second ellipse angle is given, then it is assumed that
        the blue channel defines a variable angle for the ellipse ranging from
        the first angle to the second angle given.  This allows to generate
        radial blurs, or a rough approximation for rotational blur. Or any mix
        of the two.
Cristy's avatar
Cristy committed
619
    <br/><br/>
cristy's avatar
cristy committed
620 621 622 623 624 625
    </td>
  </tr>

  </tbody>
</table>

Cristy's avatar
Cristy committed
626
<p>To print a complete list of all the available compose operators, use <a
Cristy's avatar
...  
Cristy committed
627
href="../www/command-line-options.html#list">-list compose</a>.</p>
cristy's avatar
cristy committed
628
</div>
Cristy's avatar
...  
Cristy committed
629 630
    </div>
  </main><!-- /.container -->
cristy's avatar
cristy committed
631
  <footer class="magick-footer">
Cristy's avatar
...  
Cristy committed
632 633 634
    <p><a href="../www/security-policy.html">Security</a>
    <a href="../www/architecture.html">Architecture</a>
    <a href="../www/links.html">Related</a>
Cristy's avatar
...  
Cristy committed
635 636
     <a href="../www/sitemap.html">Sitemap</a>
       
Cristy's avatar
...  
Cristy committed
637
    <a href="compose.html#"><img class="d-inline" id="logo" alt="And Now a Touch of Magick" width="16" height="16" src="../images/wand.ico"/></a>
Cristy's avatar
...  
Cristy committed
638 639 640 641 642 643
       
    <a href="http://pgp.mit.edu/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
    <a href="../www/support.html">Donate</a>
    <a href="../www/https://www.imagemagick.org/script/contact.php">Contact Us</a>
    <br/>
        <small>© 1999-2018 ImageMagick Studio LLC</small></p>
cristy's avatar
cristy committed
644 645
  </footer>

Cristy's avatar
...  
Cristy committed
646
  <!-- Javascript assets -->
Cristy's avatar
...  
Cristy committed
647 648
  <script src="assets/magick.js" crossorigin="anonymous"></script>
  <script>window.jQuery || document.write('<script src="assets/jquery.min.js"><\/script>')</script>
cristy's avatar
cristy committed
649
</body>
cristy's avatar
cristy committed
650
</html>
Cristy's avatar
...  
Cristy committed
651
<!-- Magick Cache 18th February 2018 14:40 -->