granicus.if.org Git - imagemagick/blob - www/api/layer.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\r
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\r
   4 <head>\r
   5   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U=" />\r
   6   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf" />\r
   7   <style type="text/css" media="screen,projection"><!--\r
   8     @import url("../../www/magick.css");\r
   9   --></style>\r
  10   <link rel="shortcut icon" href="../../images/wand.ico"  type="images/vnd.microsoft.icon"/>
  11   <title>ImageMagick: MagickCore, C API for ImageMagick: Dealing with Image Layers</title>
  12   <meta http-equiv="Content-Language" content="en-US"/>
  13   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  14   <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
  15   <meta name="Generator" content="PHP"/>
  16   <meta name="Keywords" content="magickcore, c, api, for, imagemagick:, dealing, with, image, layers, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
  17   <meta name="Description" content="ImageMagick® is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (about 100) including GIF, JPEG, JPEG-2000, PNG, PDF, PhotoCD, TIFF, and DPX. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.  ImageMagick is free software delivered as a ready-to-run binary distribution or as source code that you can freely use, copy, modify, and distribute. Its license is compatible with the GPL. It runs on all major operating systems.  The functionality of ImageMagick is typically utilized from the command line or you can use the features from programs written in your favorite programming language. Choose from these interfaces: MagickCore (C), MagickWand (C), ChMagick (Ch), Magick++ (C++), JMagick (Java), L-Magick (Lisp), PascalMagick (Pascal), PerlMagick (Perl), MagickWand for PHP (PHP), PythonMagick (Python), RMagick (Ruby), or TclMagick (Tcl/TK). With a language interface, use ImageMagick to modify or create images automagically and dynamically."/>
  18   <meta name="Rating" content="GENERAL"/>
  19   <meta name="Robots" content="INDEX, FOLLOW"/>
  20   <meta name="Generator" content="ImageMagick Studio LLC"/>
  21   <meta name="Author" content="ImageMagick Studio LLC"/>
  22   <meta name="Revisit-after" content="2 DAYS"/>
  23   <meta name="Resource-type" content="document"/>
  24   <meta name="Copyright" content="Copyright (c) 1999-2009 ImageMagick Studio LLC"/>
  25   <meta name="Distribution" content="Global"/>
  26 </head>\r
  27 \r
  28 <body id="www-imagemagick-org">\r
  29 <div class="titlebar">\r
  30 <a href="../../index.html">\r
  31   <img src="../../images/script.png" alt="[ImageMagick]"\r
  32   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  33 <a href="http://www.networkredux.com">\r
  34   <img src="../../images/networkredux.png" alt="[sponsor]"\r
  35   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  36 <a href="http://www.imagemagick.org/discourse-server/">\r
  37   <img src="../../images/logo.jpg" alt=""\r
  38   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  39 <a href="../../index.html">\r
  40   <img src="../../images/sprite.jpg" alt=""\r
  41   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  42 </div>\r
  43 \r
  44 <div class="eastbar">\r
  45 \r
  46 <div class="menu">
  47   <a href="../../index.html">About ImageMagick</a>
  48 </div>
  49 <div class="sep"></div>\r
  50 <div class="menu">
  51   <a href="../../www/command-line-tools.html">Command-line Tools</a>
  52 </div>
  53 <div class="sub">
  54     <a href="../../www/command-line-processing.html">Processing</a>
  55 </div>
  56 <div class="sub">
  57     <a href="../../www/command-line-options.html">Options</a>
  58 </div>
  59 <div class="sub">
  60     <a href="http://www.imagemagick.org/Usage/">Usage</a>
  61 </div>
  62 <div class="menu">
  63   <a href="../../www/api.html">Program Interfaces</a>
  64 </div>
  65 <div class="sub">
  66     <a href="../../www/magick-wand.html">MagickWand</a>
  67 </div>
  68 <div class="sub">
  69     <a href="../../www/magick-core.html">MagickCore</a>
  70 </div>
  71 <div class="sub">
  72     <a href="../../www/perl-magick.html">PerlMagick</a>
  73 </div>
  74 <div class="sub">
  75     <a href="../../Magick++/">Magick++</a>
  76 </div>
  77 <div class="menu">
  78   <a href="../../www/architecture.html">Architecture</a>
  79 </div>
  80 <div class="sep"></div>\r
  81 <div  class="menu">
  82    <a href="../../www/install-source.html">Install from Source</a>
  83 </div>
  84 <div class="sub">
  85     <a href="../../www/install-source.html#unix">Unix</a>
  86 </div>
  87 <div class="sub">
  88     <a href="../../www/install-source.html#windows">Windows</a>
  89  </div>
  90 <div class="menu">
  91   <a href="../../www/binary-releases.html">Binary Releases</a>
  92 </div>
  93 <div class="sub">
  94     <a href="../../www/binary-releases.html#unix">Unix</a>
  95 </div>
  96 <div class="sub">
  97     <a href="../../www/binary-releases.html#macosx">Mac OS X</a>
  98 </div>
  99 <div class="sub">
 100     <a href="../../www/binary-releases.html#windows">Windows</a>
 101 </div>
 102 <div class="menu">
 103   <a href="../../www/resources.html">Resources</a>
 104 </div>
 105 <div class="sep"></div>\r
 106 <div class="menu">
 107   <a href="../../www/download.html">Download</a>
 108 </div>
 109 <div class="sep"></div>\r
 110 <div class="menu">
 111   <a href="../http://www.imagemagick.org/script/search.php">Search</a>
 112 </div>
 113 <div class="sep"></div>\r
 114 <div class="menu">
 115   <a href="../../www/sitemap.html">Site Map</a>
 116 </div>
 117 <div  class="sub">
 118     <a href="../../www/links.html">Links</a>
 119 </div>
 120 <div class="sep"></div>\r
 121 <div  class="menu">
 122   <a href="../../www/sponsors.html">Sponsors:</a>
 123
 124 <div class="sponsbox">
 125 <div  class="sponsor">
 126    <a href="http://www.abi-stoff.de/abizeitung/" title="Abibuch">Abizeitung</a><!-- 20101101000200 -->
 127 </div>
 128 <div  class="sponsor">
 129   <a href="http://www.online-kredit-index.de">Kredit</a><!-- 201004010120 Buchhorn -->
 130 </div>
 131 <div  class="sponsor">
 132   <a href="http://www.blumenversender.com">Blumenversand</a><!-- 201005010120 -->
 133 </div>
 134 <div  class="sponsor">
 135   <a href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
 136 </div>
 137 <div  class="sponsor">
 138    <a href="http://www.goyax.de">Börse</a><!-- 201001000240 Gewiese digital-finance.de -->
 139 </div>
 140 <div  class="sponsor">
 141    <a href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012001200 allesdruck.de-->
 142 </div>
 143 <div  class="sponsor">
 144   <a href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 201002010000 -->
 145 </div>
 146 </div>
 147 </div>
 148 \r
 149 \r
 150 </div>\r
 151 \r
 152 <div class="main">\r
 153 \r
 154 <p class="navigation-index">[<a href="#CoalesceImages">CoalesceImages</a> &bull; <a href="#DisposeImages">DisposeImages</a> &bull; <a href="#CompareImageLayers">CompareImageLayers</a> &bull; <a href="#DeconstructImages">DeconstructImages</a> &bull; <a href="#OptimizeImageLayers">OptimizeImageLayers</a> &bull; <a href="#OptimizeImagePlusLayers">OptimizeImagePlusLayers</a> &bull; <a href="#OptimizeImageTransparency">OptimizeImageTransparency</a> &bull; <a href="#RemoveDuplicateLayers">RemoveDuplicateLayers</a> &bull; <a href="#RemoveZeroDelayLayers">RemoveZeroDelayLayers</a> &bull; <a href="#CompositeLayers">CompositeLayers</a> &bull; <a href="#MergeImageLayers">MergeImageLayers</a>]</p>
 155
 156 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 157 _8c.html" target="source" name="CoalesceImages">CoalesceImages</a></h2>
 158 <div class="doc-section">
 159
 160 <p>CoalesceImages() composites a set of images while respecting any page offsets and disposal methods.  GIF, MIFF, and MNG animation sequences typically start with an image background and each subsequent image varies in size and offset.  A new image sequence is returned with all images the same size as the first images virtual canvas and composited with the next image in the sequence.</p></ol>
 161
 162 <p>The format of the CoalesceImages method is:</p>
 163
 164 <pre class="code">
 165   Image *CoalesceImages(Image *image,ExceptionInfo *exception)
 166 </pre>
 167
 168 <p>A description of each parameter follows:</p></ol>
 169
 170 <h5>image</h5>
 171 <ol><p>the image sequence.</p></ol>
 172
 173 <h5>exception</h5>
 174 <ol><p>return any errors or warnings in this structure.</p></ol>
 175
 176  </div>
 177 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 178 _8c.html" target="source" name="DisposeImages">DisposeImages</a></h2>
 179 <div class="doc-section">
 180
 181 <p>DisposeImages() returns the coalesced frames of a GIF animation as it would appear after the GIF dispose method of that frame has been applied.  That is it returned the appearance of each frame before the next is overlaid.</p></ol>
 182
 183 <p>The format of the DisposeImages method is:</p>
 184
 185 <pre class="code">
 186   Image *DisposeImages(Image *image,ExceptionInfo *exception)
 187 </pre>
 188
 189 <p>A description of each parameter follows:</p></ol>
 190
 191 <h5>image</h5>
 192 <ol><p>the image sequence.</p></ol>
 193
 194 <h5>exception</h5>
 195 <ol><p>return any errors or warnings in this structure.</p></ol>
 196
 197  </div>
 198 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 199 _8c.html" target="source" name="CompareImageLayers">CompareImageLayers</a></h2>
 200 <div class="doc-section">
 201
 202 <p>CompareImageLayers() compares each image with the next in a sequence and returns the minimum bounding region of all the pixel differences (of the ImageLayerMethod specified) it discovers.</p></ol>
 203
 204 <p>Images do NOT have to be the same size, though it is best that all the images are 'coalesced' (images are all the same size, on a flattened canvas, so as to represent exactly how an specific frame should look).</p></ol>
 205
 206 <p>No GIF dispose methods are applied, so GIF animations must be coalesced before applying this image operator to find differences to them.</p></ol>
 207
 208 <p>The format of the CompareImageLayers method is:</p>
 209
 210 <pre class="code">
 211   Image *CompareImageLayers(const Image *images,
 212     const ImageLayerMethod method,ExceptionInfo *exception)
 213 </pre>
 214
 215 <p>A description of each parameter follows:</p></ol>
 216
 217 <h5>image</h5>
 218 <ol><p>the image.</p></ol>
 219
 220 <h5>method</h5>
 221 <ol><p>the layers type to compare images with. Must be one of... CompareAnyLayer, CompareClearLayer, CompareOverlayLayer.</p></ol>
 222
 223 <h5>exception</h5>
 224 <ol><p>return any errors or warnings in this structure.</p></ol>
 225
 226  </div>
 227 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 228 _8c.html" target="source" name="DeconstructImages">DeconstructImages</a></h2>
 229 <div class="doc-section">
 230
 231 <p>DeconstructImages() compares each image with the next in a sequence and returns the minimum bounding region of all differences from the first image.</p></ol>
 232
 233 <p>This function is deprecated in favor of the more universal CompareImageLayers() function.</p></ol>
 234
 235 <p>The format of the DeconstructImages method is:</p>
 236
 237 <pre class="code">
 238   Image *DeconstructImages(const Image *images, ExceptionInfo *exception)
 239 </pre>
 240
 241 <p>A description of each parameter follows:</p></ol>
 242
 243 <h5>image</h5>
 244 <ol><p>the image.</p></ol>
 245
 246 <h5>exception</h5>
 247 <ol><p>return any errors or warnings in this structure.</p></ol>
 248
 249  </div>
 250 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 251 _8c.html" target="source" name="OptimizeImageLayers">OptimizeImageLayers</a></h2>
 252 <div class="doc-section">
 253
 254 <p>OptimizeImageLayers() compares each image the GIF disposed forms of the previous image in the sequence.  From this it attempts to select the smallest cropped image to replace each frame, while preserving the results of the GIF animation.</p></ol>
 255
 256 <p>The format of the OptimizeImageLayers method is:</p>
 257
 258 <pre class="code">
 259   Image *OptimizeImageLayers(const Image *image,
 260            ExceptionInfo *exception)
 261 </pre>
 262
 263 <p>A description of each parameter follows:</p></ol>
 264
 265 <h5>image</h5>
 266 <ol><p>the image.</p></ol>
 267
 268 <h5>exception</h5>
 269 <ol><p>return any errors or warnings in this structure.</p></ol>
 270
 271  </div>
 272 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 273 _8c.html" target="source" name="OptimizeImagePlusLayers">OptimizeImagePlusLayers</a></h2>
 274 <div class="doc-section">
 275
 276 <p>OptimizeImagePlusLayers() is exactly as OptimizeImageLayers(), but may also add or even remove extra frames in the animation, if it improves the total number of pixels in the resulting GIF animation.</p></ol>
 277
 278 <p>The format of the OptimizePlusImageLayers method is:</p>
 279
 280 <pre class="code">
 281   Image *OptimizePlusImageLayers(const Image *image,
 282            ExceptionInfo *exception)
 283 </pre>
 284
 285 <p>A description of each parameter follows:</p></ol>
 286
 287 <h5>image</h5>
 288 <ol><p>the image.</p></ol>
 289
 290 <h5>exception</h5>
 291 <ol><p>return any errors or warnings in this structure.</p></ol>
 292
 293  </div>
 294 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 295 _8c.html" target="source" name="OptimizeImageTransparency">OptimizeImageTransparency</a></h2>
 296 <div class="doc-section">
 297
 298 <p>OptimizeImageTransparency() takes a frame optimized GIF animation, and compares the overlayed pixels against the disposal image resulting from all the previous frames in the animation.  Any pixel that does not change the disposal image (and thus does not effect the outcome of an overlay) is made transparent.</p></ol>
 299
 300 <p>WARNING: This modifies the current images directly, rather than generate a new image sequence.</p></ol>
 301
 302 <p>The format of the OptimizeImageTransperency method is:</p>
 303
 304 <pre class="code">
 305   void OptimizeImageTransperency(Image *image,ExceptionInfo *exception)
 306 </pre>
 307
 308 <p>A description of each parameter follows:</p></ol>
 309
 310 <h5>image</h5>
 311 <ol><p>the image sequence</p></ol>
 312
 313 <h5>exception</h5>
 314 <ol><p>return any errors or warnings in this structure.</p></ol>
 315
 316  </div>
 317 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 318 _8c.html" target="source" name="RemoveDuplicateLayers">RemoveDuplicateLayers</a></h2>
 319 <div class="doc-section">
 320
 321 <p>RemoveDuplicateLayers() removes any image that is exactly the same as the next image in the given image list.  Image size and virtual canvas offset must also match, though not the virtual canvas size itself.</p></ol>
 322
 323 <p>No check is made with regards to image disposal setting, though it is the dispose setting of later image that is kept.  Also any time delays are also added together. As such coalesced image animations should still produce the same result, though with duplicte frames merged into a single frame.</p></ol>
 324
 325 <p>The format of the RemoveDuplicateLayers method is:</p>
 326
 327 <pre class="code">
 328   void RemoveDuplicateLayers(Image **image, ExceptionInfo *exception)
 329 </pre>
 330
 331 <p>A description of each parameter follows:</p></ol>
 332
 333 <h5>images</h5>
 334 <ol><p>the image list</p></ol>
 335
 336 <h5>exception</h5>
 337 <ol><p>return any errors or warnings in this structure.</p></ol>
 338
 339  </div>
 340 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 341 _8c.html" target="source" name="RemoveZeroDelayLayers">RemoveZeroDelayLayers</a></h2>
 342 <div class="doc-section">
 343
 344 <p>RemoveZeroDelayLayers() removes any image that as a zero delay time. Such images generally represent intermediate or partial updates in GIF animations used for file optimization.  They are not ment to be displayed to users of the animation.  Viewable images in an animation should have a time delay of 3 or more centi-seconds (hundredths of a second).</p></ol>
 345
 346 <p>However if all the frames have a zero time delay, then either the animation is as yet incomplete, or it is not a GIF animation.  This a non-sensible situation, so no image will be removed and a 'Zero Time Animation' warning (exception) given.</p></ol>
 347
 348 <p>No warning will be given if no image was removed because all images had an appropriate non-zero time delay set.</p></ol>
 349
 350 <p>Due to the special requirements of GIF disposal handling, GIF animations should be coalesced first, before calling this function, though that is not a requirement.</p></ol>
 351
 352 <p>The format of the RemoveZeroDelayLayers method is:</p>
 353
 354 <pre class="code">
 355   void RemoveZeroDelayLayers(Image **image, ExceptionInfo *exception)
 356 </pre>
 357
 358 <p>A description of each parameter follows:</p></ol>
 359
 360 <h5>images</h5>
 361 <ol><p>the image list</p></ol>
 362
 363 <h5>exception</h5>
 364 <ol><p>return any errors or warnings in this structure.</p></ol>
 365
 366  </div>
 367 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 368 _8c.html" target="source" name="CompositeLayers">CompositeLayers</a></h2>
 369 <div class="doc-section">
 370
 371 <p>CompositeLayers() compose first image sequence (source) over the second image sequence (destination), using the given compose method and offsets.</p></ol>
 372
 373 <p>The pointers to the image list does not have to be the start of that image list, but may start somewhere in the middle.  Each layer from the two image lists are composted together until the end of one of the image lists is reached.  The offset of each composition is also adjusted to match the virtual canvas offsets of each layer. As such the given offset is relative to the virtual canvas, and not the actual image.</p></ol>
 374
 375 <p>No GIF disposal handling is performed, so GIF animations should be coalesced before use.  However this not a requirement, and individual layer images may have any size or offset, for special compositions.</p></ol>
 376
 377 <p>Special case:- If one of the image sequences is just a single image that image is repeatally composed with all the images in the other image list. Either the source or destination lists may be the single image, for this situation.</p></ol>
 378
 379 <p>The destination list will be expanded as needed to match number of source image overlaid (from current position to end of list).</p></ol>
 380
 381 <p>The format of the CompositeLayers method is:</p>
 382
 383 <pre class="code">
 384   void CompositeLayers(Image *destination,
 385       const CompositeOperator compose, Image *source,
 386       const long x_offset, const long y_offset,
 387       ExceptionInfo *exception);
 388 </pre>
 389
 390 <p>A description of each parameter follows:</p></ol>
 391
 392 <h5>destination</h5>
 393 <ol><p>the destination images and results</p></ol>
 394
 395 <h5>source</h5>
 396 <ol><p>source image(s) for the layer composition</p></ol>
 397
 398 <h5>compose, x_offset, y_offset</h5>
 399 <ol><p>arguments passed on to CompositeImages()</p></ol>
 400
 401 <h5>exception</h5>
 402 <ol><p>return any errors or warnings in this structure.</p></ol>
 403
 404  </div>
 405 <h2><a href="http://www.imagemagick.org/api/MagickCore/layer
 406 _8c.html" target="source" name="MergeImageLayers">MergeImageLayers</a></h2>
 407 <div class="doc-section">
 408
 409 <p>MergeImageLayers() composes all the image layers from the current given image onward to produce a single image of the merged layers.</p></ol>
 410
 411 <p>The inital canvas's size depends on the given ImageLayerMethod, and is initialized using the first images background color.  The images are then compositied onto that image in sequence using the given composition that has been assigned to each individual image.</p></ol>
 412
 413 <p>The format of the MergeImageLayers is:</p>
 414
 415 <pre class="text">
 416   Image *MergeImageLayers(const Image *image,
 417     const ImageLayerMethod method, ExceptionInfo *exception)
 418 </pre>
 419
 420 <p>A description of each parameter follows:</p></ol>
 421
 422 <h5>image</h5>
 423 <ol><p>the image list to be composited together</p></ol>
 424
 425 <h5>method</h5>
 426 <ol><p>the method of selecting the size of the initial canvas.</p></ol>
 427
 428 <p>MergeLayer: Merge all layers onto a canvas just large enough to hold all the actual images. The virtual canvas of the first image is preserved but otherwise ignored.</p></ol>
 429
 430 <p>FlattenLayer: Use the virtual canvas size of first image. Images which fall outside this canvas is clipped. This can be used to 'fill out' a given virtual canvas.</p></ol>
 431
 432 <p>MosaicLayer: Start with the virtual canvas of the first image, enlarging left and right edges to contain all images. Images with negative offsets will be clipped.</p></ol>
 433
 434 <p>TrimBoundsLayer: Determine the overall bounds of all the image layers just as in "MergeLayer", then adjust the the canvas and offsets to be relative to those bounds, without overlaying the images.</p></ol>
 435
 436 <p>WARNING: a new image is not returned, the original image sequence page data is modified instead.</p></ol>
 437
 438 <h5>exception</h5>
 439 <ol><p>return any errors or warnings in this structure.</p></ol>
 440
 441  </div>
 442 \r
 443 </div>\r
 444 \r
 445 <div id="linkbar">\r
 446  <!--    <span id="linkbar-west">&nbsp;</span>  -->\r
 447     <span id="linkbar-center">\r
 448       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 449       <a href="../../www/mailing-list.html">Mailing Lists</a> &bull;\r
 450     <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 451     </span>\r
 452     <span id="linkbar-east">&nbsp;</span>\r
 453   </div>\r
 454   <div class="footer">\r
 455     <span id="footer-west">&copy; 1999-2009 ImageMagick Studio LLC</span>\r
 456     <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 457   </div>\r
 458   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 459 </body>\r
 460 </html>\r