Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 9b127f12bd0bf3a92bf7472faf48f5c21bfff42c / . / www / api / morphology.html
blob: 8dc84348658f64eef706041d2cd91cb164044067 [file] [log] [blame]
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
cristy2bd2a982011-02-15 00:52:58 +0000[diff] [blame]3<html version="-//W3C//DTD XHTML 1.1//EN"
4 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
5 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6 xsi:schemaLocation="http://www.w3.org/1999/xhtml
7 http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]8<head>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]9 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
10 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]11 <title>ImageMagick: MagickCore, C API for ImageMagick: Morphological Erosions, Dilations, Openings, and Closings</title>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]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"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]15 <meta name="Application-name" content="ImageMagick"/>
cristye6e84152011-06-06 14:16:49 +0000[diff] [blame]16 <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 automagically."/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]17 <meta name="Application-url" content="http://www.imagemagick.org"/>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]18 <meta name="Generator" content="PHP"/>
cristye6e84152011-06-06 14:16:49 +0000[diff] [blame]19 <meta name="Keywords" content="magickcore, c, api, for, imagemagick:, morphological, erosions, dilations, openings, closings, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Image, Processing, Automagically"/>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]20 <meta name="Rating" content="GENERAL"/>
21 <meta name="Robots" content="INDEX, FOLLOW"/>
22 <meta name="Generator" content="ImageMagick Studio LLC"/>
23 <meta name="Author" content="ImageMagick Studio LLC"/>
24 <meta name="Revisit-after" content="2 DAYS"/>
25 <meta name="Resource-type" content="document"/>
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]26 <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]27 <meta name="Distribution" content="Global"/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]28 <link rel="icon" href="../../images/wand.png"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]29 <link rel="shortcut icon" href="../../images/wand.ico" type="images/x-icon"/>
30 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
cristy7a40ba82011-01-08 20:31:18 +0000[diff] [blame]31 <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]32 <style type="text/css" media="all">
33 @import url("../../www/magick.css");
34 </style>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]35 <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]36 <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
37 <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
38 <script type="text/javascript">
39 $(document).ready(function() {
40 $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
41 'transitionIn' : 'elastic',
42 'transitionOut' : 'elastic',
43 'overlayShow' : false,
44 'opacity' : true
45 });
46 });
47 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]48</head>
49
50<body id="www-imagemagick-org">
51<div class="titlebar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]52<div style="margin: 17px auto; float: left;">
53 <script type="text/javascript">
54 <!--
55 google_ad_client = "pub-3129977114552745";
56 google_ad_slot = "5439289906";
57 google_ad_width = 728;
58 google_ad_height = 90;
59 //-->
60 </script>
61 <script type="text/javascript"
62 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
63 </script>
64</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]65<a href="http://www.imagemagick.org/discourse-server/">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]66 <img src="../../images/logo.jpg"
67 alt="ImageMagick Logo"
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]68 style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]69<a href="../../index.html">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]70 <img src="../../images/sprite.jpg"
71 alt="ImageMagick Sprite"
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]72 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
73</div>
74
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]75<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]76
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]77<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]78 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]79</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]80<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]81<div class="menu">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]82 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
83</div>
84<div class="sub">
85 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
86</div>
87<div class="sub">
88 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
89</div>
90<div class="sub">
cristye6e84152011-06-06 14:16:49 +0000[diff] [blame]91 <a title="Binary Release: iOS" href="../../www/binary-releases.html#iOS">iOS</a>
cristyda16f162011-02-19 23:52:17 +0000[diff] [blame]92</div>
93<div class="sub">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]94 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
95</div>
96<div class="sep"></div>
97<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]98 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]99</div>
100<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]101 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]102</div>
103<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]104 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]105</div>
106<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]107 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]108</div>
109<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]110 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]111</div>
112<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]113 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]114</div>
115<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]116 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]117</div>
118<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]119 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]120</div>
121<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]122 <a title="Program Interface: Magick++" href="../../www/magick++.html">Magick++</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]123</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]124<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]125<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]126 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]127</div>
128<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]129 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]130</div>
131<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]132 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]133 </div>
134<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]135 <a title="Resources" href="../../www/resources.html">Resources</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]136</div>
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]137<div class="menu">
138 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
139</div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]140<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]141 <a title="Download" href="../../www/download.html">Download</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]142</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]143<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]144<div class="menu">
cristy52923442011-01-15 22:54:31 +0000[diff] [blame]145 <a title="Search" href="../../www/search.html">Search</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]146</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]147<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]148<div class="menu">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]149 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]150</div>
151<div class="sub">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]152 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]153</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]154<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]155<div class="menu">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]156 <a rel="follow" title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]157
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]158<a href="http://www.networkredux.com">
159 <img src="../../images/networkredux.png" alt="[sponsor]"
160 style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]161<div class="sponsbox">
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]162<div class="sponsor">
cristy81492d62011-06-07 16:41:42 +0000[diff] [blame]163 <a rel="follow" title="Sponsor: Web Hosting" href="http://www.micfo.com">Web Hosting</a><!-- 209901010090s golestan -->
164</div>
165<div class="sponsor">
cristy84134182011-06-15 22:59:00 +0000[diff] [blame]166 <a rel="follow" title="Sponsor: Search engine optimisation" href="http://www.seomoves.com.au">Search engine optimisation</a><!-- 201110010090s jen@seo lowprofilelinks -->
167</div>
168<div class="sponsor">
cristy81492d62011-06-07 16:41:42 +0000[diff] [blame]169 <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
170</div>
171<div class="sponsor">
cristyba1758d2011-06-03 01:29:12 +0000[diff] [blame]172 <a rel="follow" title="Sponsor: Web Hosting Deals" href="http://www.webhostingdeals.org">Web Hosting Deals</a><!-- 201111010270 chee.hoa darin -->
173</div>
174<div class="sponsor">
175 <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingsecretrevealed.com">Web Hosting Secret Revealed</a><!-- 201204010540 iamchee jerry -->
176</div>
177<div class="sponsor">
cristy4bf6e232011-05-21 01:43:33 +0000[diff] [blame]178 <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]179</div>
180<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]181 <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]182</div>
183<div class="sponsor">
cristy575d5ee2011-05-24 01:59:01 +0000[diff] [blame]184 <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]185</div>
186<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]187 <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]188</div>
189<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]190 <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
cristy73fd1cd2010-09-12 19:14:25 +0000[diff] [blame]191</div>
192<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]193 <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]194</div>
195<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]196 <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame]197</div>
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]198<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]199 <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]200</div>
201<div class="sponsor">
cristy9b127f12011-06-15 23:48:41 +0000[diff] [blame^]202 <a rel="follow" title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]203</div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]204</div>
205</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]206</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]207
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]208<div class="eastbar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]209
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]210</div>
211
212<div class="main">
213
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]214<h1>Module morphology Methods</h1>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]215<p class="navigation-index">[<a href="#** This macro IsNaN">** This macro IsNaN</a> &bull; <a href="#AcquireKernelInfo">AcquireKernelInfo</a> &bull; <a href="#AcquireKernelBuiltIn">AcquireKernelBuiltIn</a> &bull; <a href="#CloneKernelInfo">CloneKernelInfo</a> &bull; <a href="#DestroyKernelInfo">DestroyKernelInfo</a> &bull; <a href="#MorphologyApply">MorphologyApply</a> &bull; <a href="#MorphologyImageChannel">MorphologyImageChannel</a> &bull; <a href="#ScaleGeometryKernelInfo">ScaleGeometryKernelInfo</a> &bull; <a href="#ScaleKernelInfo">ScaleKernelInfo</a> &bull; <a href="#ShowKernelInfo">ShowKernelInfo</a> &bull; <a href="#UnityAddKernelInfo">UnityAddKernelInfo</a> &bull; <a href="#ZeroKernelNans">ZeroKernelNans</a>]</p>
cristyc4960862010-05-23 22:24:24 +0000[diff] [blame]216
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]217<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="**_This macro IsNaN">** This macro IsNaN</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]218<div class="doc-section">
219
220<p>** This macro IsNaN() is thus is only true if the value given is NaN. </p>
221 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]222<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="AcquireKernelInfo">AcquireKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]223<div class="doc-section">
224
225<p>AcquireKernelInfo() takes the given string (generally supplied by the user) and converts it into a Morphology/Convolution Kernel. This allows users to specify a kernel from a number of pre-defined kernels, or to fully specify their own kernel for a specific Convolution or Morphology Operation.</p>
226
227<p>The kernel so generated can be any rectangular array of floating point values (doubles) with the 'control point' or 'pixel being affected' anywhere within that array of values.</p>
228
229<p>Previously IM was restricted to a square of odd size using the exact center as origin, this is no longer the case, and any rectangular kernel with any value being declared the origin. This in turn allows the use of highly asymmetrical kernels.</p>
230
231<p>The floating point values in the kernel can also include a special value known as 'nan' or 'not a number' to indicate that this value is not part of the kernel array. This allows you to shaped the kernel within its rectangular area. That is 'nan' values provide a 'mask' for the kernel shape. However at least one non-nan value must be provided for correct working of a kernel.</p>
232
233<p>The returned kernel should be freed using the DestroyKernelInfo() when you are finished with it. Do not free this memory yourself.</p>
234
235<p>Input kernel defintion strings can consist of any of three types.</p>
236
237<p>"name:args[[@><]" Select from one of the built in kernels, using the name and geometry arguments supplied. See AcquireKernelBuiltIn()</p>
238
239<p>"WxH[+X+Y][@><]:num, num, num ..." a kernel of size W by H, with W*H floating point numbers following. the 'center' can be optionally be defined at +X+Y (such that +0+0 is top left corner). If not defined the pixel in the center, for odd sizes, or to the immediate top or left of center for even sizes is automatically selected.</p>
240
241<p>"num, num, num, num, ..." list of floating point numbers defining an 'old style' odd sized square kernel. At least 9 values should be provided for a 3x3 square kernel, 25 for a 5x5 square kernel, 49 for 7x7, etc. Values can be space or comma separated. This is not recommended.</p>
242
cristybe3c5be2011-03-05 17:35:07 +0000[diff] [blame]243<p>You can define a 'list of kernels' which can be used by some morphology operators A list is defined as a semi-colon separated list kernels.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]244
245<p>" kernel ; kernel ; kernel ; "</p>
246
247<p>Any extra ';' characters, at start, end or between kernel defintions are simply ignored.</p>
248
249<p>The special flags will expand a single kernel, into a list of rotated kernels. A '@' flag will expand a 3x3 kernel into a list of 45-degree cyclic rotations, while a '>' will generate a list of 90-degree rotations. The '<' also exands using 90-degree rotates, but giving a 180-degree reflected kernel before the +/- 90-degree rotations, which can be important for Thinning operations.</p>
250
251<p>Note that 'name' kernels will start with an alphabetic character while the new kernel specification has a ':' character in its specification string. If neither is the case, it is assumed an old style of a simple list of numbers generating a odd-sized square kernel has been given.</p>
252
253<p>The format of the AcquireKernal method is:</p>
254
255<pre class="code">
256 KernelInfo *AcquireKernelInfo(const char *kernel_string)
257</pre>
258
259<p>A description of each parameter follows:</p>
260
261<h5>kernel_string</h5>
262<p>the Morphology/Convolution kernel wanted.</p>
263
264 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]265<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="AcquireKernelBuiltIn">AcquireKernelBuiltIn</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]266<div class="doc-section">
267
268<p>AcquireKernelBuiltIn() returned one of the 'named' built-in types of kernels used for special purposes such as gaussian blurring, skeleton pruning, and edge distance determination.</p>
269
270<p>They take a KernelType, and a set of geometry style arguments, which were typically decoded from a user supplied string, or from a more complex Morphology Method that was requested.</p>
271
272<p>The format of the AcquireKernalBuiltIn method is:</p>
273
274<pre class="code">
275 KernelInfo *AcquireKernelBuiltIn(const KernelInfoType type,
276 const GeometryInfo args)
277</pre>
278
279<p>A description of each parameter follows:</p>
280
281<h5>type</h5>
282<p>the pre-defined type of kernel wanted</p>
283
284<h5>args</h5>
285<p>arguments defining or modifying the kernel</p>
286
287<p>Convolution Kernels</p>
288
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]289<p>Unity The a No-Op or Scaling single element kernel.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]290
291<p>Gaussian:{radius},{sigma} Generate a two-dimentional gaussian kernel, as used by -gaussian. The sigma for the curve is required. The resulting kernel is normalized,</p>
292
293<p>If 'sigma' is zero, you get a single pixel on a field of zeros.</p>
294
295<p>NOTE: that the 'radius' is optional, but if provided can limit (clip) the final size of the resulting kernel to a square 2*radius+1 in size. The radius should be at least 2 times that of the sigma value, or sever clipping and aliasing may result. If not given or set to 0 the radius will be determined so as to produce the best minimal error result, which is usally much larger than is normally needed.</p>
296
297<p>LoG:{radius},{sigma} "Laplacian of a Gaussian" or "Mexician Hat" Kernel. The supposed ideal edge detection, zero-summing kernel.</p>
298
299<p>An alturnative to this kernel is to use a "DoG" with a sigma ratio of approx 1.6 (according to wikipedia).</p>
300
301<p>DoG:{radius},{sigma1},{sigma2} "Difference of Gaussians" Kernel. As "Gaussian" but with a gaussian produced by 'sigma2' subtracted from the gaussian produced by 'sigma1'. Typically sigma2 > sigma1. The result is a zero-summing kernel.</p>
302
303<p>Blur:{radius},{sigma}[,{angle}] Generates a 1 dimensional or linear gaussian blur, at the angle given (current restricted to orthogonal angles). If a 'radius' is given the kernel is clipped to a width of 2*radius+1. Kernel can be rotated by a 90 degree angle.</p>
304
305<p>If 'sigma' is zero, you get a single pixel on a field of zeros.</p>
306
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]307<p>Note that two convolutions with two "Blur" kernels perpendicular to each other, is equivalent to a far larger "Gaussian" kernel with the same sigma value, However it is much faster to apply. This is how the "-blur" operator actually works.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]308
309<p>Comet:{width},{sigma},{angle} Blur in one direction only, much like how a bright object leaves a comet like trail. The Kernel is actually half a gaussian curve, Adding two such blurs in opposite directions produces a Blur Kernel. Angle can be rotated in multiples of 90 degrees.</p>
310
311<p>Note that the first argument is the width of the kernel and not the radius of the kernel.</p>
312
313<p># Still to be implemented... # # Filter2D # Filter1D # Set kernel values using a resize filter, and given scale (sigma) # Cylindrical or Linear. Is this posible with an image? #</p>
314
315<p>Named Constant Convolution Kernels</p>
316
317<p>All these are unscaled, zero-summing kernels by default. As such for non-HDRI version of ImageMagick some form of normalization, user scaling, and biasing the results is recommended, to prevent the resulting image being 'clipped'.</p>
318
319<p>The 3x3 kernels (most of these) can be circularly rotated in multiples of 45 degrees to generate the 8 angled varients of each of the kernels.</p>
320
321<p>Laplacian:{type} Discrete Lapacian Kernels, (without normalization) Type 0 : 3x3 with center:8 surounded by -1 (8 neighbourhood) Type 1 : 3x3 with center:4 edge:-1 corner:0 (4 neighbourhood) Type 2 : 3x3 with center:4 edge:1 corner:-2 Type 3 : 3x3 with center:4 edge:-2 corner:1 Type 5 : 5x5 laplacian Type 7 : 7x7 laplacian Type 15 : 5x5 LoG (sigma approx 1.4) Type 19 : 9x9 LoG (sigma approx 1.4)</p>
322
323<p>Sobel:{angle} Sobel 'Edge' convolution kernel (3x3) | -1, 0, 1 | | -2, 0,-2 | | -1, 0, 1 |</p>
324
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]325<p>Roberts:{angle} Roberts convolution kernel (3x3) | 0, 0, 0 | | -1, 1, 0 | | 0, 0, 0 |</p>
326
327<p>Prewitt:{angle} Prewitt Edge convolution kernel (3x3) | -1, 0, 1 | | -1, 0, 1 | | -1, 0, 1 |</p>
328
329<p>Compass:{angle} Prewitt's "Compass" convolution kernel (3x3) | -1, 1, 1 | | -1,-2, 1 | | -1, 1, 1 |</p>
330
331<p>Kirsch:{angle} Kirsch's "Compass" convolution kernel (3x3) | -3,-3, 5 | | -3, 0, 5 | | -3,-3, 5 |</p>
332
333<p>FreiChen:{angle} Frei-Chen Edge Detector is based on a kernel that is similar to the Sobel Kernel, but is designed to be isotropic. That is it takes into account the distance of the diagonal in the kernel.</p>
334
335<p>| 1, 0, -1 | | sqrt(2), 0, -sqrt(2) | | 1, 0, -1 |</p>
336
337<p>FreiChen:{type},{angle}</p>
338
339<p>Frei-Chen Pre-weighted kernels...</p>
340
341<p>Type 0: default un-nomalized version shown above.</p>
342
343<p>Type 1: Orthogonal Kernel (same as type 11 below) | 1, 0, -1 | | sqrt(2), 0, -sqrt(2) | / 2*sqrt(2) | 1, 0, -1 |</p>
344
345<p>Type 2: Diagonal form of Kernel... | 1, sqrt(2), 0 | | sqrt(2), 0, -sqrt(2) | / 2*sqrt(2) | 0, -sqrt(2) -1 |</p>
346
347<p>However this kernel is als at the heart of the FreiChen Edge Detection Process which uses a set of 9 specially weighted kernel. These 9 kernels not be normalized, but directly applied to the image. The results is then added together, to produce the intensity of an edge in a specific direction. The square root of the pixel value can then be taken as the cosine of the edge, and at least 2 such runs at 90 degrees from each other, both the direction and the strength of the edge can be determined.</p>
348
349<p>Type 10: All 9 of the following pre-weighted kernels...</p>
350
351<p>Type 11: | 1, 0, -1 | | sqrt(2), 0, -sqrt(2) | / 2*sqrt(2) | 1, 0, -1 |</p>
352
353<p>Type 12: | 1, sqrt(2), 1 | | 0, 0, 0 | / 2*sqrt(2) | 1, sqrt(2), 1 |</p>
354
355<p>Type 13: | sqrt(2), -1, 0 | | -1, 0, 1 | / 2*sqrt(2) | 0, 1, -sqrt(2) |</p>
356
357<p>Type 14: | 0, 1, -sqrt(2) | | -1, 0, 1 | / 2*sqrt(2) | sqrt(2), -1, 0 |</p>
358
359<p>Type 15: | 0, -1, 0 | | 1, 0, 1 | / 2 | 0, -1, 0 |</p>
360
361<p>Type 16: | 1, 0, -1 | | 0, 0, 0 | / 2 | -1, 0, 1 |</p>
362
363<p>Type 17: | 1, -2, 1 | | -2, 4, -2 | / 6 | -1, -2, 1 |</p>
364
365<p>Type 18: | -2, 1, -2 | | 1, 4, 1 | / 6 | -2, 1, -2 |</p>
366
367<p>Type 19: | 1, 1, 1 | | 1, 1, 1 | / 3 | 1, 1, 1 |</p>
368
369<p>The first 4 are for edge detection, the next 4 are for line detection and the last is to add a average component to the results.</p>
370
371<p>Using a special type of '-1' will return all 9 pre-weighted kernels as a multi-kernel list, so that you can use them directly (without normalization) with the special "-set option:morphology:compose Plus" setting to apply the full FreiChen Edge Detection Technique.</p>
372
373<p>If 'type' is large it will be taken to be an actual rotation angle for the default FreiChen (type 0) kernel. As such FreiChen:45 will look like a Sobel:45 but with 'sqrt(2)' instead of '2' values.</p>
374
375<p>WARNING: The above was layed out as per http://www.math.tau.ac.il/~turkel/notes/edge_detectors.pdf But rotated 90 degrees so direction is from left rather than the top. I have yet to find any secondary confirmation of the above. The only other source found was actual source code at http://ltswww.epfl.ch/~courstiv/exos_labos/sol3.pdf Neigher paper defineds the kernels in a way that looks locical or correct when taken as a whole.</p>
376
377<p>Boolean Kernels</p>
378
379<p>Diamond:[{radius}[,{scale}]] Generate a diamond shaped kernel with given radius to the points. Kernel size will again be radius*2+1 square and defaults to radius 1, generating a 3x3 kernel that is slightly larger than a square.</p>
380
381<p>Square:[{radius}[,{scale}]] Generate a square shaped kernel of size radius*2+1, and defaulting to a 3x3 (radius 1).</p>
382
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]383<p>Octagon:[{radius}[,{scale}]] Generate octagonal shaped kernel of given radius and constant scale. Default radius is 3 producing a 7x7 kernel. A radius of 1 will result in "Diamond" kernel.</p>
384
385<p>Disk:[{radius}[,{scale}]] Generate a binary disk, thresholded at the radius given, the radius may be a float-point value. Final Kernel size is floor(radius)*2+1 square. A radius of 5.3 is the default.</p>
386
387<p>NOTE: That a low radii Disk kernels produce the same results as many of the previously defined kernels, but differ greatly at larger radii. Here is a table of equivalences... "Disk:1" => "Diamond", "Octagon:1", or "Cross:1" "Disk:1.5" => "Square" "Disk:2" => "Diamond:2" "Disk:2.5" => "Octagon" "Disk:2.9" => "Square:2" "Disk:3.5" => "Octagon:3" "Disk:4.5" => "Octagon:4" "Disk:5.4" => "Octagon:5" "Disk:6.4" => "Octagon:6" All other Disk shapes are unique to this kernel, but because a "Disk" is more circular when using a larger radius, using a larger radius is preferred over iterating the morphological operation.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]388
389<p>Rectangle:{geometry} Simply generate a rectangle of 1's with the size given. You can also specify the location of the 'control point', otherwise the closest pixel to the center of the rectangle is selected.</p>
390
391<p>Properly centered and odd sized rectangles work the best.</p>
392
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]393<p>Symbol Dilation Kernels</p>
394
395<p>These kernel is not a good general morphological kernel, but is used more for highlighting and marking any single pixels in an image using, a "Dilate" method as appropriate.</p>
396
397<p>For the same reasons iterating these kernels does not produce the same result as using a larger radius for the symbol.</p>
398
399<p>Plus:[{radius}[,{scale}]] Cross:[{radius}[,{scale}]] Generate a kernel in the shape of a 'plus' or a 'cross' with a each arm the length of the given radius (default 2).</p>
400
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]401<p>NOTE: "plus:1" is equivalent to a "Diamond" kernel.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]402
403<p>Ring:{radius1},{radius2}[,{scale}] A ring of the values given that falls between the two radii. Defaults to a ring of approximataly 3 radius in a 7x7 kernel. This is the 'edge' pixels of the default "Disk" kernel, More specifically, "Ring" -> "Ring:2.5,3.5,1.0"</p>
404
405<p>Hit and Miss Kernels</p>
406
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]407<p>Peak:radius1,radius2 Find any peak larger than the pixels the fall between the two radii. The default ring of pixels is as per "Ring". Edges Find flat orthogonal edges of a binary shape Corners Find 90 degree corners of a binary shape Diagonals:type A special kernel to thin the 'outside' of diagonals LineEnds:type Find end points of lines (for pruning a skeletion) Two types of lines ends (default to both) can be searched for Type 0: All line ends Type 1: single kernel for 4-conneected line ends Type 2: single kernel for simple line ends LineJunctions Find three line junctions (within a skeletion) Type 0: all line junctions Type 1: Y Junction kernel Type 2: Diagonal T Junction kernel Type 3: Orthogonal T Junction kernel Type 4: Diagonal X Junction kernel Type 5: Orthogonal + Junction kernel Ridges:type Find single pixel ridges or thin lines Type 1: Fine single pixel thick lines and ridges Type 2: Find two pixel thick lines and ridges ConvexHull Octagonal Thickening Kernel, to generate convex hulls of 45 degrees Skeleton:type Traditional skeleton generating kernels. Type 1: Tradional Skeleton kernel (4 connected skeleton) Type 2: HIPR2 Skeleton kernel (8 connected skeleton) Type 3: Thinning skeleton based on a ressearch paper by Dan S. Bloomberg (Default Type) ThinSE:type A huge variety of Thinning Kernels designed to preserve conectivity. many other kernel sets use these kernels as source definitions. Type numbers are 41-49, 81-89, 481, and 482 which are based on the super and sub notations used in the source research paper.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]408
409<p>Distance Measuring Kernels</p>
410
411<p>Different types of distance measuring methods, which are used with the a 'Distance' morphology method for generating a gradient based on distance from an edge of a binary shape, though there is a technique for handling a anti-aliased shape.</p>
412
413<p>See the 'Distance' Morphological Method, for information of how it is applied.</p>
414
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]415<p>Chebyshev:[{radius}][x{scale}[!]] Chebyshev Distance (also known as Tchebychev or Chessboard distance) is a value of one to any neighbour, orthogonal or diagonal. One why of thinking of it is the number of squares a 'King' or 'Queen' in chess needs to traverse reach any other position on a chess board. It results in a 'square' like distance function, but one where diagonals are given a value that is closer than expected.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]416
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]417<p>Manhattan:[{radius}][x{scale}[!]] Manhattan Distance (also known as Rectilinear, City Block, or the Taxi Cab distance metric), it is the distance needed when you can only travel in horizontal or vertical directions only. It is the distance a 'Rook' in chess would have to travel, and results in a diamond like distances, where diagonals are further than expected.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]418
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]419<p>Octagonal:[{radius}][x{scale}[!]] An interleving of Manhatten and Chebyshev metrics producing an increasing octagonally shaped distance. Distances matches those of the "Octagon" shaped kernel of the same radius. The minimum radius and default is 2, producing a 5x5 kernel.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]420
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]421<p>Euclidean:[{radius}][x{scale}[!]] Euclidean distance is the 'direct' or 'as the crow flys' distance. However by default the kernel size only has a radius of 1, which limits the distance to 'Knight' like moves, with only orthogonal and diagonal measurements being correct. As such for the default kernel you will get octagonal like distance function.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]422
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]423<p>However using a larger radius such as "Euclidean:4" you will get a much smoother distance gradient from the edge of the shape. Especially if the image is pre-processed to include any anti-aliasing pixels. Of course a larger kernel is slower to use, and not always needed.</p>
424
425<p>The first three Distance Measuring Kernels will only generate distances of exact multiples of {scale} in binary images. As such you can use a scale of 1 without loosing any information. However you also need some scaling when handling non-binary anti-aliased shapes.</p>
426
427<p>The "Euclidean" Distance Kernel however does generate a non-integer fractional results, and as such scaling is vital even for binary shapes.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]428
429 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]430<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="CloneKernelInfo">CloneKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]431<div class="doc-section">
432
433<p>CloneKernelInfo() creates a new clone of the given Kernel List so that its can be modified without effecting the original. The cloned kernel should be destroyed using DestoryKernelInfo() when no longer needed.</p>
434
435<p>The format of the CloneKernelInfo method is:</p>
436
437<pre class="code">
438 KernelInfo *CloneKernelInfo(const KernelInfo *kernel)
439</pre>
440
441<p>A description of each parameter follows:</p>
442
443<h5>kernel</h5>
444<p>the Morphology/Convolution kernel to be cloned</p>
445
446 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]447<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="DestroyKernelInfo">DestroyKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]448<div class="doc-section">
449
450<p>DestroyKernelInfo() frees the memory used by a Convolution/Morphology kernel.</p>
451
452<p>The format of the DestroyKernelInfo method is:</p>
453
454<pre class="code">
455 KernelInfo *DestroyKernelInfo(KernelInfo *kernel)
456</pre>
457
458<p>A description of each parameter follows:</p>
459
460<h5>kernel</h5>
461<p>the Morphology/Convolution kernel to be destroyed</p>
462
463 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]464<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="MorphologyApply">MorphologyApply</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]465<div class="doc-section">
466
467<p>MorphologyApply() applies a morphological method, multiple times using a list of multiple kernels.</p>
468
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]469<p>It is basically equivalent to as MorphologyImageChannel() (see below) but without any user controls. This allows internel programs to use this function, to actually perform a specific task without posible interference by any API user supplied settings.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]470
471<p>It is MorphologyImageChannel() task to extract any such user controls, and pass them to this function for processing.</p>
472
473<p>More specifically kernels are not normalized/scaled/blended by the 'convolve:scale' Image Artifact (setting), nor is the convolve bias (-bias setting or image->bias) loooked at, but must be supplied from the function arguments.</p>
474
475<p>The format of the MorphologyApply method is:</p>
476
477<pre class="code">
478 Image *MorphologyApply(const Image *image,MorphologyMethod method,
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]479 const ChannelType channel, const ssize_t iterations,
480 const KernelInfo *kernel, const CompositeMethod compose,
481 const double bias, ExceptionInfo *exception)
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]482</pre>
483
484<p>A description of each parameter follows:</p>
485
486<h5>image</h5>
487<p>the source image</p>
488
489<h5>method</h5>
490<p>the morphology method to be applied.</p>
491
cristye9a32c32011-04-07 01:11:05 +0000[diff] [blame]492<h5>channel</h5>
493<p>the channels to which the operations are applied The channel 'sync' flag determines if 'alpha weighting' is applied for convolution style operations.</p>
494
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]495<h5>iterations</h5>
496<p>apply the operation this many times (or no change). A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.</p>
497
498<h5>channel</h5>
499<p>the channel type.</p>
500
501<h5>kernel</h5>
502<p>An array of double representing the morphology kernel.</p>
503
504<h5>compose</h5>
505<p>How to handle or merge multi-kernel results. If 'UndefinedCompositeOp' use default for the Morphology method. If 'NoCompositeOp' force image to be re-iterated by each kernel. Otherwise merge the results using the compose method given.</p>
506
507<h5>bias</h5>
508<p>Convolution Output Bias.</p>
509
510<h5>exception</h5>
511<p>return any errors or warnings in this structure.</p>
512
513 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]514<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="MorphologyImageChannel">MorphologyImageChannel</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]515<div class="doc-section">
516
517<p>MorphologyImageChannel() applies a user supplied kernel to the image according to the given mophology method.</p>
518
519<p>This function applies any and all user defined settings before calling the above internal function MorphologyApply().</p>
520
521<p>User defined settings include... * Output Bias for Convolution and correlation ("-bias") * Kernel Scale/normalize settings ("-set 'option:convolve:scale'") This can also includes the addition of a scaled unity kernel. * Show Kernel being applied ("-set option:showkernel 1")</p>
522
523<p>The format of the MorphologyImage method is:</p>
524
525<pre class="code">
526 Image *MorphologyImage(const Image *image,MorphologyMethod method,
527 const ssize_t iterations,KernelInfo *kernel,ExceptionInfo *exception)
528</pre>
529
530<p>Image *MorphologyImageChannel(const Image *image, const ChannelType channel,MorphologyMethod method,const ssize_t iterations, KernelInfo *kernel,ExceptionInfo *exception)</p>
531
532<p>A description of each parameter follows:</p>
533
534<h5>image</h5>
535<p>the image.</p>
536
537<h5>method</h5>
538<p>the morphology method to be applied.</p>
539
540<h5>iterations</h5>
541<p>apply the operation this many times (or no change). A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.</p>
542
543<h5>channel</h5>
544<p>the channel type.</p>
545
546<h5>kernel</h5>
547<p>An array of double representing the morphology kernel. Warning: kernel may be normalized for the Convolve method.</p>
548
549<h5>exception</h5>
550<p>return any errors or warnings in this structure.</p>
551
552 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]553<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ScaleGeometryKernelInfo">ScaleGeometryKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]554<div class="doc-section">
555
556<p>ScaleGeometryKernelInfo() takes a geometry argument string, typically provided as a "-set option:convolve:scale {geometry}" user setting, and modifies the kernel according to the parsed arguments of that setting.</p>
557
558<p>The first argument (and any normalization flags) are passed to ScaleKernelInfo() to scale/normalize the kernel. The second argument is then passed to UnityAddKernelInfo() to add a scled unity kernel into the scaled/normalized kernel.</p>
559
560<p>The format of the ScaleGeometryKernelInfo method is:</p>
561
562<pre class="code">
563 void ScaleGeometryKernelInfo(KernelInfo *kernel,
564 const double scaling_factor,const MagickStatusType normalize_flags)
565</pre>
566
567<p>A description of each parameter follows:</p>
568
569<h5>kernel</h5>
570<p>the Morphology/Convolution kernel to modify</p>
571
572<p>o geometry:</p>
573
574<pre class="text">
575 "-set option:convolve:scale {geometry}" setting.
576</pre>
577
578 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]579<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ScaleKernelInfo">ScaleKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]580<div class="doc-section">
581
582<p>ScaleKernelInfo() scales the given kernel list by the given amount, with or without normalization of the sum of the kernel values (as per given flags).</p>
583
584<p>By default (no flags given) the values within the kernel is scaled directly using given scaling factor without change.</p>
585
586<p>If either of the two 'normalize_flags' are given the kernel will first be normalized and then further scaled by the scaling factor value given.</p>
587
588<p>Kernel normalization ('normalize_flags' given) is designed to ensure that any use of the kernel scaling factor with 'Convolve' or 'Correlate' morphology methods will fall into -1.0 to +1.0 range. Note that for non-HDRI versions of IM this may cause images to have any negative results clipped, unless some 'bias' is used.</p>
589
590<p>More specifically. Kernels which only contain positive values (such as a 'Gaussian' kernel) will be scaled so that those values sum to +1.0, ensuring a 0.0 to +1.0 output range for non-HDRI images.</p>
591
592<p>For Kernels that contain some negative values, (such as 'Sharpen' kernels) the kernel will be scaled by the absolute of the sum of kernel values, so that it will generally fall within the +/- 1.0 range.</p>
593
594<p>For kernels whose values sum to zero, (such as 'Laplician' kernels) kernel will be scaled by just the sum of the postive values, so that its output range will again fall into the +/- 1.0 range.</p>
595
cristybe3c5be2011-03-05 17:35:07 +0000[diff] [blame]596<p>For special kernels designed for locating shapes using 'Correlate', (often only containing +1 and -1 values, representing foreground/brackground matching) a special normalization method is provided to scale the positive values separately to those of the negative values, so the kernel will be forced to become a zero-sum kernel better suited to such searches.</p>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]597
598<p>WARNING: Correct normalization of the kernel assumes that the '*_range' attributes within the kernel structure have been correctly set during the kernels creation.</p>
599
600<p>NOTE: The values used for 'normalize_flags' have been selected specifically to match the use of geometry options, so that '!' means NormalizeValue, '^' means CorrelateNormalizeValue. All other GeometryFlags values are ignored.</p>
601
602<p>The format of the ScaleKernelInfo method is:</p>
603
604<pre class="code">
605 void ScaleKernelInfo(KernelInfo *kernel, const double scaling_factor,
606 const MagickStatusType normalize_flags )
607</pre>
608
609<p>A description of each parameter follows:</p>
610
611<h5>kernel</h5>
612<p>the Morphology/Convolution kernel</p>
613
614<p>o scaling_factor:</p>
615
616<pre class="text">
617 zero. If the kernel is normalized regardless of any flags.
618</pre>
619
620<p>o normalize_flags:</p>
621
622<pre class="text">
623 specifically: NormalizeValue, CorrelateNormalizeValue,
624 and/or PercentValue
625</pre>
626
627 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]628<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ShowKernelInfo">ShowKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]629<div class="doc-section">
630
631<p>ShowKernelInfo() outputs the details of the given kernel defination to standard error, generally due to a users 'showkernel' option request.</p>
632
633<p>The format of the ShowKernel method is:</p>
634
635<pre class="code">
636 void ShowKernelInfo(KernelInfo *kernel)
637</pre>
638
639<p>A description of each parameter follows:</p>
640
641<h5>kernel</h5>
642<p>the Morphology/Convolution kernel</p>
643
644 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]645<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="UnityAddKernelInfo">UnityAddKernelInfo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]646<div class="doc-section">
647
648<p>UnityAddKernelInfo() Adds a given amount of the 'Unity' Convolution Kernel to the given pre-scaled and normalized Kernel. This in effect adds that amount of the original image into the resulting convolution kernel. This value is usually provided by the user as a percentage value in the 'convolve:scale' setting.</p>
649
650<p>The resulting effect is to convert the defined kernels into blended soft-blurs, unsharp kernels or into sharpening kernels.</p>
651
652<p>The format of the UnityAdditionKernelInfo method is:</p>
653
654<pre class="code">
655 void UnityAdditionKernelInfo(KernelInfo *kernel, const double scale )
656</pre>
657
658<p>A description of each parameter follows:</p>
659
660<h5>kernel</h5>
661<p>the Morphology/Convolution kernel</p>
662
663<p>o scale:</p>
664
665<pre class="text">
666 the given kernel.
667</pre>
668
669 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]670<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ZeroKernelNans">ZeroKernelNans</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]671<div class="doc-section">
672
673<p>ZeroKernelNans() replaces any special 'nan' value that may be present in the kernel with a zero value. This is typically done when the kernel will be used in special hardware (GPU) convolution processors, to simply matters.</p>
674
675<p>The format of the ZeroKernelNans method is:</p>
676
677<pre class="code">
678 void ZeroKernelNans (KernelInfo *kernel)
679</pre>
680
681<p>A description of each parameter follows:</p>
682
683<h5>kernel</h5>
684<p>the Morphology/Convolution kernel</p>
685
686 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]687
688</div>
689
690<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]691 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]692 <span id="linkbar-center">
693 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]694 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]695 </span>
696 <span id="linkbar-east">&nbsp;</span>
697 </div>
698 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]699 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]700 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
701 </div>
702 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]703 <script type="text/javascript">
704 var _gaq = _gaq || [];
705 _gaq.push(['_setAccount', 'UA-17690367-1']);
706 _gaq.push(['_trackPageview']);
707
708 (function() {
709 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
710 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
711 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
712 })();
713 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]714</body>
715</html>