Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 874404737e1da30e7e48b6ab2e2fe183a21565ba / . / www / api / morphology.html
blob: f76717e255f95a07e081bec76472b8332f1fdf22 [file] [log] [blame]
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cristy2c839602010-04-03 02:32:08 +0000[diff] [blame]3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]4<head>
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]5 <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]6 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U=" />
7 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf" />
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]8 <style type="text/css" media="all">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]9 @import url("../../www/magick.css");
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]10 </style>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]11 <link rel="shortcut icon" href="../../images/wand.ico" type="images/vnd.microsoft.icon"/>
12 <title>ImageMagick: MagickCore, C API for ImageMagick: Morphological Erosions, Dilations, Openings, and Closings</title>
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="Generator" content="PHP"/>
17 <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, Swiss, Army, Knife, Image, Processing"/>
18 <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."/>
19 <meta name="Rating" content="GENERAL"/>
20 <meta name="Robots" content="INDEX, FOLLOW"/>
21 <meta name="Generator" content="ImageMagick Studio LLC"/>
22 <meta name="Author" content="ImageMagick Studio LLC"/>
23 <meta name="Revisit-after" content="2 DAYS"/>
24 <meta name="Resource-type" content="document"/>
25 <meta name="Copyright" content="Copyright (c) 1999-2010 ImageMagick Studio LLC"/>
26 <meta name="Distribution" content="Global"/>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]27</head>
28
29<body id="www-imagemagick-org">
30<div class="titlebar">
31<a href="../../index.html">
32 <img src="../../images/script.png" alt="[ImageMagick]"
33 style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
34<a href="http://www.networkredux.com">
35 <img src="../../images/networkredux.png" alt="[sponsor]"
36 style="margin: 45px auto; border: 0px; float: left;" /></a>
37<a href="http://www.imagemagick.org/discourse-server/">
38 <img src="../../images/logo.jpg" alt=""
39 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
40<a href="../../index.html">
41 <img src="../../images/sprite.jpg" alt=""
42 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
43</div>
44
45<div class="eastbar">
46
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]47<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]48 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]49</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]50<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]51<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]52 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]53</div>
54<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]55 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]56</div>
57<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]58 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]59</div>
60<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]61 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]62</div>
63<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]64 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]65</div>
66<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]67 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]68</div>
69<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]70 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]71</div>
72<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]73 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]74</div>
75<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]76 <a title="Program Interface: Magick++" href="../../Magick++/">Magick++</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]77</div>
78<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]79 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]80</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]81<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]82<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]83 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]84</div>
85<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]86 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]87</div>
88<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]89 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]90 </div>
91<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]92 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]93</div>
94<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]95 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]96</div>
97<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]98 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</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="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]102</div>
103<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]104 <a title="Resources" href="../../www/resources.html">Resources</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]105</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]106<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]107<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]108 <a title="Download" href="../../www/download.html">Download</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]109</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]110<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]111<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]112 <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]113</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]114<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]115<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]116 <a title="Site Map"href="../../www/sitemap.html">Site Map</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="Site Map: Links"href="../../www/links.html">Links</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]120</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]121<div class="sep"></div>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]122<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]123 <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]124
125<div class="sponsbox">
126<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]127 <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
cristyb36feb22010-03-26 16:54:37 +0000[diff] [blame]128</div>
129<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]130 <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]131</div>
132<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]133 <a title="Sponsor: Deko.net" href="http://www.deko.net">Deko.net</a><!-- 201101010600 Peterssen-->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]134</div>
135<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]136 <a title="Sponsor: Kredit" href="http://www.online-kredit-index.de">Kredit</a><!-- 201007010120 Buchhorn -->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]137</div>
138<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]139 <a title="Sponsor: Druckerei" href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]140</div>
141<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]142 <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]143</div>
144<div class="sponsor">
cristy80fc9be2010-05-08 20:28:34 +0000[diff] [blame]145 <a title="Sponsor: Webdesign" href="http://www.renehornig.com/" title="Webdesign">Webdesign</a><!-- 20110101000120 -->
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]146</div>
147</div>
148</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]149
150
151</div>
152
153<div class="main">
154
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]155<p class="navigation-index">[<a href="#same variable That is the IsNaN">same variable That is the 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="#ExpandKernelInfo">ExpandKernelInfo</a> &bull; <a href="#MorphologyImageChannel">MorphologyImageChannel</a> &bull; <a href="#ScaleKernelInfo">ScaleKernelInfo</a>]</p>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]156
157<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
158_8c.html" target="source" name="same variable That is the IsNaN">same variable That is the IsNaN</a></h2>
159<div class="doc-section">
160
161<p>same variable That is the IsNaN() macro is only true if the value is NaN. </p>
162 </div>
163<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
164_8c.html" target="source" name="AcquireKernelInfo">AcquireKernelInfo</a></h2>
165<div class="doc-section">
166
167<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></ol>
168
169<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></ol>
170
171<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></ol>
172
173<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></ol>
174
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]175<p>The returned kernel should be freed using the DestroyKernelInfo() when you are finished with it. Do not free this memory yourself.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]176
177<p>Input kernel defintion strings can consist of any of three types.</p></ol>
178
179<p>"name:args" Select from one of the built in kernels, using the name and geometry arguments supplied. See AcquireKernelBuiltIn()</p></ol>
180
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]181<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]182
183<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></ol>
184
185<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></ol>
186
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]187<p>You can define a 'list of kernels' which can be used by some morphology operators A list is defined as a semi-colon seperated list kernels.</p></ol>
188
189<p>" kernel ; kernel ; kernel ; "</p></ol>
190
191<p>Extra ';' characters are simply ignored.</p></ol>
192
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]193<p>The format of the AcquireKernal method is:</p>
194
195<pre class="code">
196 KernelInfo *AcquireKernelInfo(const char *kernel_string)
197</pre>
198
199<p>A description of each parameter follows:</p></ol>
200
201<h5>kernel_string</h5>
202<ol><p>the Morphology/Convolution kernel wanted.</p></ol>
203
204 </div>
205<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
206_8c.html" target="source" name="AcquireKernelBuiltIn">AcquireKernelBuiltIn</a></h2>
207<div class="doc-section">
208
209<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></ol>
210
211<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></ol>
212
213<p>The format of the AcquireKernalBuiltIn method is:</p>
214
215<pre class="code">
216 KernelInfo *AcquireKernelBuiltIn(const KernelInfoType type,
217 const GeometryInfo args)
218</pre>
219
220<p>A description of each parameter follows:</p></ol>
221
222<h5>type</h5>
223<ol><p>the pre-defined type of kernel wanted</p></ol>
224
225<h5>args</h5>
226<ol><p>arguments defining or modifying the kernel</p></ol>
227
228<p>Convolution Kernels</p></ol>
229
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]230<p>Gaussian:{radius},{sigma} Generate a two-dimentional gaussian kernel, as used by -gaussian. A sigma is required.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]231
232<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></ol>
233
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]234<p>Blur:{radius},{sigma},{angle} As per Gaussian, but 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. Angle can be rotated in multiples of 90 degrees.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]235
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]236<p>Note that two such blurs perpendicular to each other is equivelent to the far large "Gaussian" kernel, but much faster to apply. This is how the -blur operator works.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]237
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]238<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]239
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]240<p>Note that the first argument is the width of the kernel and not the radius of the kernel.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]241
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]242<p># Still to be implemented... # # DOG:{radius},{sigma1},{sigma2} # Difference of two Gaussians # # Filter2D # Filter1D # Set kernel values using a resize filter, and given scale (sigma) # Cylindrical or Linear. Is this posible with an image? #</p></ol>
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]243
244<p>Named Constant Convolution Kernels</p></ol>
245
246<p>Sobel:[angle] The 3x3 sobel convolution kernel. Angle may be given in multiples of 45 degrees. Kernel is unscaled by default so some normalization may be required to ensure results are not clipped. Default kernel is -1,0,1 -2,0,2 -1,0,1</p></ol>
247
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]248<p>Laplacian:{type} Generate Lapacian kernel of the type specified. (1 is the default) Type 0 default square laplacian 3x3: all -1's with central 8 Type 1 3x3: central 4 edge -1 corner 0 Type 2 3x3: central 4 edge 1 corner -2 Type 3 a 5x5 laplacian Type 4 a 7x7 laplacian</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]249
250<p>Boolean Kernels</p></ol>
251
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]252<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]253
254<p>Properly centered and odd sized rectangles work the best.</p></ol>
255
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]256<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]257
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]258<p>Square:[{radius}[,{scale}]] Generate a square shaped kernel of size radius*2+1, and defaulting to a 3x3 (radius 1).</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]259
260<p>Note that using a larger radius for the "Square" or the "Diamond" is also equivelent to iterating the basic morphological method that many times. However However iterating with the smaller radius 1 default is actually faster than using a larger kernel radius.</p></ol>
261
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]262<p>Disk:[{radius}[,{scale}]] Generate a binary disk of the radius given, radius may be a float. Kernel size will be ceil(radius)*2+1 square. NOTE: Here are some disk shapes of specific interest "disk:1" => "diamond" or "cross:1" "disk:1.5" => "square" "disk:2" => "diamond:2" "disk:2.5" => a general disk shape of radius 2 "disk:2.9" => "square:2" "disk:3.5" => default - octagonal/disk shape of radius 3 "disk:4.2" => roughly octagonal shape of radius 4 "disk:4.3" => a general disk shape of radius 4 After this all the kernel shape becomes more and more circular.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]263
264<p>Because a "disk" is more circular when using a larger radius, using a larger radius is preferred over iterating the morphological operation.</p></ol>
265
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]266<p>Plus:[{radius}[,{scale}]] Cross:[{radius}[,{scale}]] Generate a kernel in the shape of a 'plus' or a cross. The length of each arm is also the radius, which defaults to 2.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]267
268<p>NOTE: "plus:1" is equivelent to a "Diamond" kernel.</p></ol>
269
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]270<p>This 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" or "Erode" method as appropriate.</p></ol>
271
272<p>For the same reasons iterating these kernels does not produce the same result as using a larger radius for the symbol.</p></ol>
273
274<p>Hit and Miss Kernels</p></ol>
275
276<p>Peak:radius1,radius2 Find a foreground inside a background ring of the given radii. Corners Find corners of a binary shape LineEnds Find end points of lines (for pruning a skeletion) LineJunctions Find three line junctions (in a skeletion) ConvexHull Octagonal thicken kernel, to generate convex hulls of 45 degrees Skeleton Thinning kernel, which leaves behind a skeletion of a shape</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]277
278<p>Distance Measuring Kernels</p></ol>
279
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]280<p>Chebyshev:[{radius}][x{scale}[!]] Manhatten:[{radius}][x{scale}[!]] Euclidean:[{radius}][x{scale}[!]]</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]281
282<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></ol>
283
284<p>Chebyshev Distance (also known as Tchebychev 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 closer than expected.</p></ol>
285
286<p>Manhatten Distance (also known as Rectilinear Distance, or the Taxi Cab metric), is the distance needed when you can only travel in orthogonal (horizontal or vertical) only. It is the distance a 'Rook' in chess would travel. It results in a diamond like distances, where diagonals are further than expected.</p></ol>
287
288<p>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, which is reasonally accurate.</p></ol>
289
290<p>However if you use a larger radius such as "Euclidean:4" you will get a much smoother distance gradient from the edge of the shape. Of course a larger kernel is slower to use, and generally not needed.</p></ol>
291
292<p>To allow the use of fractional distances that you get with diagonals the actual distance is scaled by a fixed value which the user can provide. This is not actually nessary for either ""Chebyshev" or "Manhatten" distance kernels, but is done for all three distance kernels. If no scale is provided it is set to a value of 100, allowing for a maximum distance measurement of 655 pixels using a Q16 version of IM, from any edge. However for small images this can result in quite a dark gradient.</p></ol>
293
294<p>See the 'Distance' Morphological Method, for information of how it is applied.</p></ol>
295
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]296 </div>
297<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
298_8c.html" target="source" name="CloneKernelInfo">CloneKernelInfo</a></h2>
299<div class="doc-section">
300
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]301<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]302
cristy0291e2d2010-04-04 17:50:18 +0000[diff] [blame]303<p>The format of the CloneKernelInfo method is:</p>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]304
305<pre class="code">
306 KernelInfo *CloneKernelInfo(const KernelInfo *kernel)
307</pre>
308
309<p>A description of each parameter follows:</p></ol>
310
311<h5>kernel</h5>
312<ol><p>the Morphology/Convolution kernel to be cloned</p></ol>
313
314 </div>
315<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
316_8c.html" target="source" name="DestroyKernelInfo">DestroyKernelInfo</a></h2>
317<div class="doc-section">
318
319<p>DestroyKernelInfo() frees the memory used by a Convolution/Morphology kernel.</p></ol>
320
321<p>The format of the DestroyKernelInfo method is:</p>
322
323<pre class="code">
324 KernelInfo *DestroyKernelInfo(KernelInfo *kernel)
325</pre>
326
327<p>A description of each parameter follows:</p></ol>
328
329<h5>kernel</h5>
330<ol><p>the Morphology/Convolution kernel to be destroyed</p></ol>
331
332 </div>
333<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]334_8c.html" target="source" name="ExpandKernelInfo">ExpandKernelInfo</a></h2>
335<div class="doc-section">
336
337<p>ExpandKernelInfo() takes a single kernel, and expands it into a list of kernels each incrementally rotated the angle given.</p></ol>
338
339<p>WARNING: 45 degree rotations only works for 3x3 kernels. While 90 degree roatations only works for linear and square kernels</p></ol>
340
341<p>The format of the RotateKernelInfo method is:</p>
342
343<pre class="code">
344 void ExpandKernelInfo(KernelInfo *kernel, double angle)
345</pre>
346
347<p>A description of each parameter follows:</p></ol>
348
349<h5>kernel</h5>
350<ol><p>the Morphology/Convolution kernel</p></ol>
351
352<h5>angle</h5>
353<ol><p>angle to rotate in degrees</p></ol>
354
355<p>This function is only internel to this module, as it is not finalized, especially with regard to non-orthogonal angles, and rotation of larger 2D kernels. </p>
356 </div>
357<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]358_8c.html" target="source" name="MorphologyImageChannel">MorphologyImageChannel</a></h2>
359<div class="doc-section">
360
361<p>MorphologyImageChannel() applies a user supplied kernel to the image according to the given mophology method.</p></ol>
362
363<p>The given kernel is assumed to have been pre-scaled appropriatally, usally by the kernel generator.</p></ol>
364
365<p>The format of the MorphologyImage method is:</p>
366
367<pre class="code">
368 Image *MorphologyImage(const Image *image,MorphologyMethod method,
369 const long iterations,KernelInfo *kernel,ExceptionInfo *exception)
370 Image *MorphologyImageChannel(const Image *image, const ChannelType
371 channel,MorphologyMethod method,const long iterations,
372 KernelInfo *kernel,ExceptionInfo *exception)
373</pre>
374
375<p>A description of each parameter follows:</p></ol>
376
377<h5>image</h5>
378<ol><p>the image.</p></ol>
379
380<h5>method</h5>
381<ol><p>the morphology method to be applied.</p></ol>
382
383<h5>iterations</h5>
384<ol><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></ol>
385
386<h5>channel</h5>
387<ol><p>the channel type.</p></ol>
388
389<h5>kernel</h5>
390<ol><p>An array of double representing the morphology kernel. Warning: kernel may be normalized for the Convolve method.</p></ol>
391
392<h5>exception</h5>
393<ol><p>return any errors or warnings in this structure.</p></ol>
394
395
396<p>TODO: bias and auto-scale handling of the kernel for convolution The given kernel is assumed to have been pre-scaled appropriatally, usally by the kernel generator.</p></ol>
397
398 </div>
399<h2><a href="http://www.imagemagick.org/api/MagickCore/morphology
400_8c.html" target="source" name="ScaleKernelInfo">ScaleKernelInfo</a></h2>
401<div class="doc-section">
402
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]403<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]404
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]405<p>By default (no flags given) the values within the kernel is scaled directly using given scaling factor without change.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]406
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]407<p>If any 'normalize_flags' are given the kernel will first be normalized and then further scaled by the scaling factor value given. A 'PercentValue' flag will cause the given scaling factor to be divided by one hundred percent.</p></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]408
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]409<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]410
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]411<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]412
413<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></ol>
414
415<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></ol>
416
417<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 seperatally to those of the negative values, so the kernel will be forced to become a zero-sum kernel better suited to such searches.</p></ol>
418
cristyf0d1f5d2010-05-13 16:29:38 +0000[diff] [blame]419<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></ol>
cristyd2baf7d2010-03-06 04:26:44 +0000[diff] [blame]420
421<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, and '' means PercentValue. All other GeometryFlags values are ignored.</p></ol>
422
423<p>The format of the ScaleKernelInfo method is:</p>
424
425<pre class="code">
426 void ScaleKernelInfo(KernelInfo *kernel, const double scaling_factor,
427 const MagickStatusType normalize_flags )
428</pre>
429
430<p>A description of each parameter follows:</p></ol>
431
432<h5>kernel</h5>
433<ol><p>the Morphology/Convolution kernel</p></ol>
434
435<p>o scaling_factor:</p>
436
437<pre class="text">
438 zero. If the kernel is normalized regardless of any flags.
439</pre>
440
441<p>o normalize_flags:</p>
442
443<pre class="text">
444 specifically: NormalizeValue, CorrelateNormalizeValue,
445 and/or PercentValue
446</pre>
447
448<p>This function is internal to this module only at this time, but can be exported to other modules if needed. </p>
449 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]450
451</div>
452
453<div id="linkbar">
454 <!-- <span id="linkbar-west">&nbsp;</span> -->
455 <span id="linkbar-center">
456 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristy6f6c2962010-05-14 01:39:00 +0000[diff] [blame]457 <a href="http://studio.webbyland.com/ImageMagick/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]458 </span>
459 <span id="linkbar-east">&nbsp;</span>
460 </div>
461 <div class="footer">
462 <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>
463 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
464 </div>
465 <div style="clear: both; margin: 0; width: 100%; "></div>
466</body>
467</html>