Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / ec6694d886b4c3a418321bf5df1b3a730330ffd3 / . / www / compose.html
blob: d9e1729dde3dc6de336ab64b441916db2e55baab [file] [log] [blame]
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]1
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
cristy2bd2a982011-02-15 00:52:58 +0000[diff] [blame]4<html version="-//W3C//DTD XHTML 1.1//EN"
5 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
6 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
7 xsi:schemaLocation="http://www.w3.org/1999/xhtml
8 http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]9<head>
10 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
11 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]12 <title>ImageMagick: Alpha Compositing</title>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]13 <meta http-equiv="Content-Language" content="en-US"/>
14 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
15 <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
16 <meta name="Application-name" content="ImageMagick"/>
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]17 <meta name="Description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats. In addition resize, rotate, shear, distort and transform images."/>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]18 <meta name="Application-url" content="http://www.imagemagick.org"/>
19 <meta name="Generator" content="PHP"/>
20 <meta name="Keywords" content="alpha, compositing, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
21 <meta name="Rating" content="GENERAL"/>
22 <meta name="Robots" content="INDEX, FOLLOW"/>
23 <meta name="Generator" content="ImageMagick Studio LLC"/>
24 <meta name="Author" content="ImageMagick Studio LLC"/>
25 <meta name="Revisit-after" content="2 DAYS"/>
26 <meta name="Resource-type" content="document"/>
cristy7e41fe82010-12-04 23:12:08 +0000[diff] [blame]27 <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]28 <meta name="Distribution" content="Global"/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]29 <link rel="icon" href="../images/wand.png"/>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]30 <link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon"/>
31 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
cristy7a40ba82011-01-08 20:31:18 +0000[diff] [blame]32 <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]33 <style type="text/css" media="all">
34 @import url("../www/magick.css");
35 </style>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]36 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
cristy361f4662010-12-31 23:02:52 +0000[diff] [blame]37 <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
38 <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
39 <script type="text/javascript">
40 $(document).ready(function() {
41 $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
42 'transitionIn' : 'elastic',
43 'transitionOut' : 'elastic',
44 'overlayShow' : false,
45 'opacity' : true
46 });
47 });
48 </script>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]49</head>
50
51<body id="www-imagemagick-org">
52<div class="titlebar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]53<div style="margin: 17px auto; float: left;">
54 <script type="text/javascript">
55 <!--
56 google_ad_client = "pub-3129977114552745";
57 google_ad_slot = "5439289906";
58 google_ad_width = 728;
59 google_ad_height = 90;
60 //-->
61 </script>
62 <script type="text/javascript"
63 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
64 </script>
65</div>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]66<a href="http://www.imagemagick.org/discourse-server/">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]67 <img src="../images/logo.jpg"
68 alt="ImageMagick Logo"
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]69 style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]70<a href="../index.html">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]71 <img src="../images/sprite.jpg"
72 alt="ImageMagick Sprite"
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]73 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
74</div>
75
76<div class="westbar">
77
78<div class="menu">
79 <a title="About ImageMagick" href="../index.html">About ImageMagick</a>
80</div>
81<div class="sep"></div>
82<div class="menu">
83 <a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
84</div>
85<div class="sub">
86 <a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
87</div>
88<div class="sub">
89 <a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
90</div>
91<div class="sub">
cristyda16f162011-02-19 23:52:17 +0000[diff] [blame]92 <a title="Binary Release: iPhone" href="../www/binary-releases.html#iPhone">iPhone</a>
93</div>
94<div class="sub">
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]95 <a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
96</div>
97<div class="sep"></div>
98<div class="menu">
99 <a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
100</div>
101<div class="sub">
102 <a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
103</div>
104<div class="sub">
105 <a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
106</div>
107<div class="sub">
108 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
109</div>
110<div class="menu">
111 <a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
112</div>
113<div class="sub">
114 <a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
115</div>
116<div class="sub">
117 <a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
118</div>
119<div class="sub">
120 <a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
121</div>
122<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]123 <a title="Program Interface: Magick++" href="../www/magick++.html">Magick++</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]124</div>
125<div class="sep"></div>
126<div class="menu">
127 <a title="Install from Source" href="../www/install-source.html">Install from Source</a>
128</div>
129<div class="sub">
130 <a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
131</div>
132<div class="sub">
133 <a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
134 </div>
135<div class="menu">
136 <a title="Resources" href="../www/resources.html">Resources</a>
137</div>
138<div class="menu">
139 <a title="Architecture" href="../www/architecture.html">Architecture</a>
140</div>
141<div class="menu">
142 <a title="Download" href="../www/download.html">Download</a>
143</div>
144<div class="sep"></div>
145<div class="menu">
cristy52923442011-01-15 22:54:31 +0000[diff] [blame]146 <a title="Search" href="../www/search.html">Search</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]147</div>
148<div class="sep"></div>
149<div class="menu">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]150 <a title="Site Map" href="../www/sitemap.html">Site Map</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]151</div>
152<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]153 <a title="Site Map: Links" href="../www/links.html">Links</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]154</div>
155<div class="sep"></div>
156<div class="menu">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]157 <a rel="follow" title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]158
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]159<a href="http://www.networkredux.com">
160 <img src="../images/networkredux.png" alt="[sponsor]"
161 style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]162<div class="sponsbox">
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]163<div class="sponsor">
cristy4bf6e232011-05-21 01:43:33 +0000[diff] [blame]164 <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
cristy45dbd322011-03-27 16:40:38 +0000[diff] [blame]165</div>
166<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]167 <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
cristy4c54bbb2011-03-17 13:53:13 +0000[diff] [blame]168</div>
169<div class="sponsor">
cristy575d5ee2011-05-24 01:59:01 +0000[diff] [blame]170 <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201110010090 alexanian media -->
cristy4bf6e232011-05-21 01:43:33 +0000[diff] [blame]171</div>
172<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]173 <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]174</div>
175<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]176 <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
cristy7d52cd62010-10-01 17:26:59 +0000[diff] [blame]177</div>
178<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]179 <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
cristyee742642011-02-26 02:49:59 +0000[diff] [blame]180</div>
181<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]182 <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]183</div>
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]184<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]185 <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]186</div>
187<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]188 <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]189</div>
190<div class="sponsor">
cristyc7364032011-05-27 02:05:42 +0000[diff] [blame]191 <a rel="follow" title="Sponsor: Bildbearbeitung" href="http://www.bildschliff.de">Bildbearbeitung</a><!-- 2012060100300 strait.de-->
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]192</div>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]193</div>
194</div>
195</div>
196
197<div class="eastbar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]198
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]199</div>
200
201<div class="main">
202
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]203<h1>ImageMagick Image Composition</h1>
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]204<p>This page descibed the Image composition methods that is used to define how
205two images should be merged together in various image operations. For the
206Command Line API it is typically set using the <A
207HREF="../www/command-line-options.html#compose" >-compose</A> setting option. </p>
208
209
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]210<p>The description of composition uses abstract terminology in order to allow
211the description to be more precise, while avoiding constant values which are
212specific to a particular build configuration. Each image pixel is represented
213by red, green, and blue levels (which are equal for a gray pixel). The
214build-dependent value <em class="QR">QuantumRange</em> is the maximum integral
215value which may be stored, per pixel, in the red, green, or blue channels of
216the image. Each image pixel may also optionally (if the image matte channel is
217enabled) have an associated level of opacity, ranging from <em>opaque</em> to
218<em>transparent</em>, which may be used to determine the influence of the pixel
219color when compositing the pixel with another image pixel. If the image matte
220channel is disabled, then all pixels in the image are treated as opaque. The
221color of an opaque pixel is fully visible while the color of a transparent
222pixel color is entirely absent (pixel color is ignored).</p>
223
224<p>By definition, raster images have a rectangular shape. All image rows are of
225equal length, as are all image columns. By treating the alpha channel as a
226visual "mask" the rectangular image may be given a "shape" by treating the
227alpha channel as a cookie-cutter for the image. This is done by setting the
228pixels within the shape to be opaque, with pixels outside the shape set as
229transparent. Pixels on the boundary of the shape may be between opaque and
230transparent in order to provide antialiasing (visually smooth edges). The
231description of the composition operators use this concept of image "shape" in
232order to make the description of the operators easier to understand. While it
233is convenient to describe the operators in terms of "shapes" they are by no
234means limited to mask-style operations since they are based on continuous
235floating-point mathematics rather than simple boolean operations.</p>
236
237<p>The following alpha blending (Duff-Porter) compose methods are available:</p>
238
239<table class="doc">
240 <tbody>
241 <tr valign="top">
242 <th align="left" style="width: 8%">Method</th>
243 <th align="left">Description</th>
244 </tr>
245
246 <tr valign="top">
247 <td valign="top">clear</td>
248 <td valign="top">Both the color and the alpha of the destination are
249 cleared. Neither the source nor the destination are used (except for
250 destinations size and other meta-data which is always preserved.</td>
251 </tr>
252
253 <tr valign="top">
254 <td valign="top">src</td>
255 <td valign="top">The source is copied to the destination. The destination
256 is not used as input, though it is cleared.</td>
257 </tr>
258
259 <tr valign="top">
260 <td valign="top">dst</td>
261 <td valign="top">The destination is left untouched. The source image is
262 completely ignored.</td>
263 </tr>
264
265 <tr valign="top">
266 <td valign="top">src-over</td>
267 <td valign="top">The source is composited over the destination. this is
268 the default alpha blending compose method, when neither the compose
269 setting is set, nor is set in the image meta-data.</td>
270 </tr>
271
272 <tr valign="top">
273 <td valign="top">dst-over</td>
274 <td valign="top">The destination is composited over the source and the
275 result replaces the destination.</td>
276 </tr>
277
278 <tr valign="top">
279 <td valign="top">src-in</td>
280 <td valign="top">The part of the source lying inside of the destination
281 replaces the destination.</td>
282 </tr>
283
284 <tr valign="top">
285 <td valign="top">dst-in</td>
286 <td valign="top">The part of the destination lying inside of the source
287 replaces the destination. Areas not overlaid are cleared.</td>
288 </tr>
289
290 <tr valign="top">
291 <td valign="top">src-out</td>
292 <td valign="top">The part of the source lying outside of the destination
293 replaces the destination.</td>
294 </tr>
295
296 <tr valign="top">
297 <td valign="top">dst-out</td>
298 <td valign="top">The part of the destination lying outside of the source
299 replaces the destination.</td>
300 </tr>
301
302 <tr valign="top">
303 <td valign="top">src-atop</td>
304 <td valign="top">The part of the source lying inside of the destination is
305 composited onto the destination.</td>
306 </tr>
307
308 <tr valign="top">
309 <td valign="top">dst-atop</td>
310 <td valign="top">The part of the destination lying inside of the source is
311 composited over the source and replaces the destination. Areas not
312 overlaid are cleared. </td>
313 </tr>
314
315 <tr valign="top">
316 <td valign="top">xor</td>
317 <td valign="top">The part of the source that lies outside of the
318 destination is combined with the part of the destination that lies
319 outside of the source. Source or Destination, but not both. </td>
320 </tr>
321
322 </tbody>
323</table>
324
325<p>Any of the 'Src-*' methods can also be specified without the 'Src-' part.
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]326For example the default compose method can be specified as just 'Over'.</p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]327
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]328<p>Many of these compose methods will clear the destination image which was
329not overlaid by the source image. This is to be expected as part of that
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]330specific composition methods defintion. You can disable this by setting the
331special <A HREF="../www/command-line-options.html#define"
332>-define</A> 'compose:outside-overlay' to a value of 'false' will turn off
333this behaviour. </p>
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]334
335<p>On top of the above 12 Duff-Porter Alpha Composition methods, one special
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]336related method '<kbd>Copy</kbd>' has been provided. This is equivalent to
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]337using the '<kbd>Src</kbd>' with the special <A HREF="../www/command-line-options.html#define"
338>-define</A> option '<kbd>compose:outside-overlay</kbd>' set to
339'<kbd>false</kbd>', so as to only modify the overlaid area, without clearing
340the rest of the image outside the overlaid area. </p>
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]341
342<br><br>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]343
344<p>The following mathemathical composition methods are also available. </p>
345
346<table class="doc">
347 <tbody>
348 <tr valign="top">
349 <th align="left" style="width: 8%">Method</th>
350 <th align="left">Description</th>
351 </tr>
352
353 <tr valign="top">
354 <td valign="top">multiply</td>
355 <td valign="top">The source is multiplied by the destination and replaces
356 the destination. The resultant color is always at least as dark as
357 either of the two constituent colors. Multiplying any color with black
358 produces black. Multiplying any color with white leaves the original
359 color unchanged.</td>
360 </tr>
361
362 <tr valign="top">
363 <td valign="top">screen</td>
364 <td valign="top">The source and destination are complemented and then
365 multiplied and then replace the destination. The resultant color is
366 always at least as light as either of the two constituent colors.
367 Screening any color with white produces white. Screening any color
368 with black leaves the original color unchanged.</td>
369 </tr>
370
371 <tr valign="top">
372 <td valign="top">plus</td>
373 <td valign="top">The source is added to the destination and replaces the
374 destination. This operator is useful for averaging or a controled
375 merger of two images, rather than a direct overlay.</td>
376 </tr>
377
378 <tr valign="top">
379 <td valign="top">add</td>
380 <td valign="top">As per 'plus' but transparency data is treated as matte
381 values. As such any transparent areas in either image remain
382 transparent. </td>
383 </tr>
384
385 <tr valign="top">
386 <td valign="top">minus</td>
387 <td valign="top">Subtract the colors in the source image from the
388 destination image. When transparency is involved, opaque areas is
389 subtracted from any destination opaque areas. </td>
390 </tr>
391
392 <tr valign="top">
393 <td valign="top">subtract</td>
394 <td valign="top">Subtract the colors in the source image from the
395 destination image. When transparency is involved transparent areas are
396 subtracted, so only the opaque areas in the source remain opaque in
397 the destination image. </td>
398 </tr>
399
400 <tr valign="top">
401 <td valign="top">difference</td>
402 <td valign="top">Subtracts the darker of the two constituent colors from
403 the lighter. Painting with white inverts the destination color.
404 Painting with black produces no change.</td>
405 </tr>
406
407 <tr valign="top">
408 <td valign="top">exclusion</td>
409 <td valign="top">Produces an effect similar to that of 'difference', but
410 appears as lower contrast. Painting with white inverts the
411 destination color. Painting with black produces no change.</td>
412 </tr>
413
414 <tr valign="top">
415 <td valign="top">darken</td>
416 <td valign="top">Selects the darker of the destination and source colors.
417 The destination is replaced with the source when the source is darker,
418 otherwise it is left unchanged.</td>
419 </tr>
420
421 <tr valign="top">
422 <td valign="top">lighten</td>
423 <td valign="top">Selects the lighter of the destination and source colors.
424 The destination is replaced with the source when the source is
425 lighter, otherwise it is left unchanged. </td>
426 </tr>
427
428 </tbody>
429</table>
430
431<p>Typically these use the default 'Over' alpha blending when transparencies
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]432are also involved, except for 'Plus' which uses a 'plus' alpha blending. This
433means the alpha channel of both images will only be used to ensure that any
434visible input remains visible even in parts not overlaid. It also means that
435any values are weighted by the alpha channel of the input and output images.
436This 'Over' alpha blending is also applied to the lighting composition methods
437below. </p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]438
439<p>As of IM v6.6.1-6, if the special '<kbd>Sync</kbd>' flag is not specified
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]440(enabled by default) with the <a href="../www/command-line-options.html#channel"
441>-channel</a> setting, then the above mathematical compositions will nolonger
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]442syncronise its actions with the alpha channel. Instead the math composition
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]443will be applied on an individual channel basis as defined by the <a
444href="../www/command-line-options.html#channel"
445>-channel</a>. This includes the alpha channel. This special usage
446allows you to perform true mathematics of the image channels, without alpha
447compostion effects, becomming involved. </p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]448
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]449<p>This special flag is not applied to the lighting composition methods (see
450below) even though they are closely related to mathematical composition
451methods.</p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]452
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]453<br><br>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]454
455<p>The following lighting composition methods are also available. </p>
456
457<table class="doc">
458 <tbody>
459 <tr valign="top">
460 <th align="left" style="width: 8%">Method</th>
461 <th align="left">Description</th>
462 </tr>
463
464 <tr valign="top">
465 <td valign="top">linear-dodge</td>
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]466 <td valign="top">This is equivalent to 'Plus' in that the color channels
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]467 are simply added, however it does not 'Plus' the alpha channel, but
468 uses the normal 'Over' alpha blending, which transparencies are
469 involved. Produces a sort of additive multiply-like result. Added
470 ImageMagick version 6.5.4-3. </td>
471 </tr>
472
473 <tr valign="top">
474 <td valign="top">linear-burn</td>
475 <td valign="top">As 'Linear-Dodge', but also subtract one from the result.
476 Sort of a additive 'Screen' of the images. Added ImageMagick version
477 6.5.4-3. </td>
478 </tr>
479
480 <tr valign="top">
481 <td valign="top">color-dodge</td>
482 <td valign="top">Brightens the destination color to reflect the source
483 color. Painting with black produces no change.</td>
484 </tr>
485
486 <tr valign="top">
487 <td valign="top">color-burn</td>
488 <td valign="top">Darkens the destination color to reflect the source
489 color. Painting with white produces no change. Fixed in ImageMagick
490 version 6.5.4-3. </td>
491 </tr>
492
493 <tr valign="top">
494 <td valign="top">overlay</td>
495 <td valign="top">Multiplies or screens the colors, dependent on the
496 destination color. Source colors overlay the destination whilst
497 preserving its highlights and shadows. The destination color is not
498 replaced, but is mixed with the source color to reflect the lightness
499 or darkness of the destination.</td>
500 </tr>
501
502 <tr valign="top">
503 <td valign="top">hard-light</td>
504 <td valign="top">Multiplies or screens the colors, dependent on the source
505 color value. If the source color is lighter than 0.5, the destination
506 is lightened as if it were screened. If the source color is darker
507 than 0.5, the destination is darkened, as if it were multiplied. The
508 degree of lightening or darkening is proportional to the difference
509 between the source color and 0.5. If it is equal to 0.5 the
510 destination is unchanged. Painting with pure black or white produces
511 black or white.</td>
512 </tr>
513
514
515 <tr valign="top">
516 <td valign="top">linear-light</td>
517 <td valign="top">Like 'Hard-Light' but using linear-dodge and linear-burn
518 instead. Increases contrast slightly with an impact on the
519 foreground's tonal values.</td>
520 </tr>
521
522 <tr valign="top">
523 <td valign="top">soft-light</td>
524 <td valign="top">Darkens or lightens the colors, dependent on the source
525 color value. If the source color is lighter than 0.5, the destination
526 is lightened. If the source color is darker than 0.5, the destination
527 is darkened, as if it were burned in. The degree of darkening or
528 lightening is proportional to the difference between the source color
529 and 0.5. If it is equal to 0.5, the destination is unchanged. Painting
530 with pure black or white produces a distinctly darker or lighter area,
531 but does not result in pure black or white. Fixed in ImageMagick
532 version 6.5.4-3. </td>
533 </tr>
534
535 <tr valign="top">
536 <td valign="top">pegtop-light</td>
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]537 <td valign="top">Almost equivalent to 'Soft-Light', but using a
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]538 continuious mathematical formula rather than two conditionally
539 selected formulae. Added ImageMagick version 6.5.4-3. </td>
540 </tr>
541
542 <tr valign="top">
543 <td valign="top">vivid-light</td>
544 <td valign="top">A modified 'Linear-Light' designed to preserve very stong
545 primary and secondary colors in the image. Added ImageMagick version
546 6.5.4-3. </td>
547 </tr>
548
549 <tr valign="top">
550 <td valign="top">pin-light</td>
551 <td valign="top">Similar to 'Hard-Light', but using sharp linear shadings,
552 to similate the effects of a strong 'pinhole' light source. Added
553 ImageMagick version 6.5.4-3. </td>
554 </tr>
555
556 </tbody>
557</table>
558
559
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]560<br><br>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]561
562<p>Also included are these special purpose compose methods:</p>
563
564<table class="doc">
565 <tbody>
566 <tr valign="top">
567 <th align="left" style="width: 8%">Method</th>
568 <th align="left">Description</th>
569 </tr>
570
571 <tr valign="top">
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]572 <td valign="top">copy</td>
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]573 <td valign="top">This is equivalent to the Duff-Porter composition method
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]574 '<kbd>Src,</kbd>' but without clearing the parts of the destination
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]575 image that is not overlaid. </td>
576 </tr>
577
578 <tr valign="top">
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]579 <td valign="top">copy-*</td>
580 <td valign="top">Copy the specified channel (Red, Green, Blue, Cyan,
581 Magenta, Yellow, Black, or Opacity) in the source image to the
582 same channel in the destination image. If the channel specified
583 does not exist in the source image, (which can only happen for methods,
584 '<kbd>copy-opacity</kbd>' or '<kbd>copy-black</kbd>') then it is
585 assumed that the source image is a special grayscale channel image
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]586 of the values that is to be copied. </td>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]587 </tr>
588
589 <tr valign="top">
590 <td valign="top">change-mask</td>
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]591 <td valign="top">Replace any destination pixel that is the similar to the
592 source images pixel (as defined by the current <a
593 href="../www/command-line-options.html#fuzz">-fuzz</a> factor), with transparency.
594 </td>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]595 </tr>
596 </tbody>
597</table>
598
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]599<br><br>
600
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]601<p>On top of these composed methods are a few special ones that not only require
602the two images that are being merged or overlaid, but have some extra numerical
603arguments, which are tabled below. </p>
604
605<p>In the "<code>composite</code>" command these composition methods are
606selected using special options with the arguments needed. They are usually,
607but not always, the same name as the composte 'method' they use, and replaces
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]608the normal use of the <a href="../www/command-line-options.html#compose" >-compose</a>
609setting in the "<code>composite</code>" command. For example... </p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]610
611<p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>composite ... -blend 50x50 ...</span></p>
612<p>As of IM v6.5.3-4 the "<code>convert</code>" command can now also supply
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]613these extra arguments to its <a href="../www/command-line-options.html#composite"
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]614>-composite</a> operator, using the special <a href="../www/command-line-options.html#define">-define</a>
615attribute of '<kbd class="arg">compose:args</kbd>'. This means you can now
616make use of these special argumented <a href="../www/command-line-options.html#compose"
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]617>-compose</a> methods, those the argument and the method both need to be set
618separatally. For example... </p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]619
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]620<p class='crt'><span class="crtprompt"> $magick&gt; </span><span class='crtin'>convert ... -compose blend -define compose:args=50,50 -composite ...</span></p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]621<p>The following is a table of these special 'argumented' compose methods,
622with a brief summary of what they do. For more details see the equivalent
623"composite" command option name. </p>
624
625<table class="doc">
626 <tbody>
627 <tr valign="top">
628 <th align="left" style="width: 8%">Method</th>
629 <th align="left">Description</th>
630 </tr>
631
632 <tr valign="top">
633 <td valign="top">dissolve</td>
634 <td valign="top">Arguments:
635 <em class="arg">src_percent</em>[x<em class="arg">dst_percent</em>]
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]636 <br>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#dissolve">-dissolve</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]637 <br>Dissolve the 'source' image by the percentage given before overlaying
638 'over' the 'destination' image. If <em class="arg">src_percent</em> is
639 greater than 100, it starts dissolving the main image so it will
640 become transparent at a value of '<kbd class="arg">200</kbd>'. If
641 both percentages are given, each image are dissolved to the
642 percentages given.
643 </td>
644 </tr>
645
646 <tr valign="top">
647 <td valign="top">blend</td>
648 <td valign="top">Arguments:
649 <em class="arg">src_percent</em>[x<em class="arg">dst_percent</em>]
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]650 <br>Equivalent to "<code>composite</code>" <a
651 href="../www/command-line-options.html#blend">-blend</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]652 <br>Average the images together ('plus') according to the percentages
653 given and each pixels transparency. If only a single percentage value
654 is given it sets the weight of the composite or 'source' image, while
655 the background image is weighted by the exact opposite amount. That is
656 a <kbd>-blend 30</kbd> merges 30% of the 'source' image with 70% of
657 the 'destination' image. Thus it is equivalent to <kbd>-blend
658 30x70</kbd>.
659 </td>
660 </tr>
661
662 <tr valign="top">
663 <td valign="top">mathematics</td>
664 <td valign="top">Arguments: <em class="arg">A, B, C, D</em>
665 <br>Not available in "<code>composite</code>" at this time.
666 <br>Merge the source and destination images according to the formula
667 <br>&nbsp; &nbsp; &nbsp;<code>A*Sc*Dc + B*Sc + C*Dc + D</code>
668 <br>Can be used to generate a custom composition method that would
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]669 otherwise need to be implemented using the slow <a
670 href="../www/command-line-options.html#fx">-fx</a> DIY image operator. Added
671 to ImageMagick version 6.5.4-3.
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]672 <br>As of IM v6.6.1-6 this method will do per-channel math compositions
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]673 if the 'Sync' flag is removed from <a
674 href="../www/command-line-options.html#channel" >-channel</a>, just like all
675 the other mathematical compostion methods above.
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]676 </td>
677 </tr>
678
679 <tr valign="top">
680 <td valign="top">modulate</td>
681 <td valign="top">Arguments:
682 <em class="arg">brightness</em>[x<em class="arg">saturation</em>]
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]683 <br>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#watermark">-watermark</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]684 <br>Take a grayscale image (with alpha mask) and modify the destination
685 image's brightness according to watermark image's grayscale value and
686 the <em class="arg">brightness</em> percentage. The destinations
687 color saturation attribute is just direct modified by the <em
688 class="arg">saturation</em> percentage, which defaults to 100 percent
689 (no color change).
690
691 </td>
692 </tr>
693
694 <tr valign="top">
695 <td valign="top">displace</td>
696 <td valign="top">Arguments:
697 <em class="arg">X-scale</em>[x<em class="arg">Y-scale</em>][!][%]
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]698 <br>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#displace">-displace</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]699 <br>With this option, the 'overlay' image, and optionally the 'mask'
700 image, is used as a relative displacement map, which is used to
701 displace the lookup of what part of the destination image is seen at
702 each point of the overlaid area. Much like the displacement map is a
703 'lens' that distorts the original 'background' image behind it.
704 <br><br>
705 The X-scale is modilated by the 'red' channel of the overlay image
706 while the Y-scale is modulated by the green channel, (the mask image
707 if given is rolled into green channel of the overlay image. This
708 separation allows you to modulate the X and Y lookup displacement
709 separatally allowing you to di 2 dimentional displacements, rather
710 than 1 dimentional verctored displacements (using grayscale image).
711 <br><br>
712 If the overlay image contains transparency this is used as a mask
713 of the resulting image to remove 'invalid' pixels.
714 <br><br>
715 The '%' flag makes the displacement scale relative to the size of the
716 overlay image (100% = half width/height of image). Using '!' switches
717 percentage arguments to refer to the destination image size instead.
718 <br><br>
719 Special flags were added Added to ImageMagick version 6.5.3-5.
720 </td>
721 </tr>
722
723 <tr valign="top">
724 <td valign="top">distort</td>
725 <td valign="top">Arguments:
726 <em class="arg">X-scale</em>[x<em class="arg">Y-scale</em
727 >[+<em class="arg">X-center</em>+<em class="arg">Y-center</em>]][!][%]
728 <br>Not available in "<code>composite</code>" at this time.
729 <br>Exactly as per 'Displace' (above), but using absolute coordinates,
730 relative to the center of the overlay (or that given). Basically
731 allows you to generate absolute distortion maps where 'black' will
732 look up the left/top edge, and 'white' looks up the bottom/right
733 edge of the destination image, according to the scale given.
734 <br><br>
735 The '!' flag not only switches percentage scaling, to use the
736 destination image, but also the image the center offset of the lookup.
737 This means the overlay can lookup a completely different region of the
738 destination image.
739 <br><br>
740 Added to ImageMagick version 6.5.3-5.
741 </td>
742 </tr>
743
744 <tr valign="top">
745 <td valign="top">blur</td>
746 <td valign="top">Arguments:
747 <em class="arg">Width</em>[x<em class="arg">Height</em
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]748 >[+<em class="arg">Angle</em>][+<em class="arg">Angle2</em>]]
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]749 <br>Equivalent to "<code>composite</code>" <a href="../www/command-line-options.html#blur-composite">-blur</a>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]750 <br>A Variable Blur Mapping Composition method, where each pixel in the
751 overlaid region is replaced with an Elliptical Weighted Average (EWA),
752 with an ellipse (typically a circle) of the given sigma size, scaled
753 according to overlay (source image) grayscale mapping.
754 <br><br>
755 As per 'Displace' and 'Distort', the red channel will modulate the
756 width of the ellipse, while the green channel will modulate the height
cristy075ad252010-10-30 21:56:17 +0000[diff] [blame]757 of the ellipse. If a single Angle value is given in the arguments,
758 then the ellipse will then be rotated by the angle specifed.
759 <br><br>
760 Normally the blue channel of the mapping overlay image is ignored.
761 However if a second ellipse angle is given, then it is assumed that
762 the blue channel defines a variable angle for the ellipse ranging from
763 the first angle to the second angle given. This allows to generate
764 radial blurs, or a rough approximation for rotational blur. Or any mix
765 of the two.
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]766 <br><br>
767 Added to ImageMagick version 6.5.4-0.
768 </td>
769 </tr>
770
771 </tbody>
772</table>
773
774<p>To print a complete list of all the available compose operators, use <a
cristyabd337d2010-08-17 01:06:59 +0000[diff] [blame]775href="../www/command-line-options.html#list">-list compose</a>.</p>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]776
777
778
779</div>
780
781<div id="linkbar">
782 <span id="linkbar-west">&nbsp;</span>
783 <span id="linkbar-center">
784 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
785 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
786 </span>
787 <span id="linkbar-east">&nbsp;</span>
788 </div>
789 <div class="footer">
cristy7e41fe82010-12-04 23:12:08 +0000[diff] [blame]790 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristybc9539a2010-08-16 18:06:20 +0000[diff] [blame]791 <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
792 </div>
793 <div style="clear: both; margin: 0; width: 100%; "></div>
794 <script type="text/javascript">
795 var _gaq = _gaq || [];
796 _gaq.push(['_setAccount', 'UA-17690367-1']);
797 _gaq.push(['_trackPageview']);
798
799 (function() {
800 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
801 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
802 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
803 })();
804 </script>
805</body>
806</html>