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

   1
   2
   3
   4
   5 <!DOCTYPE html>
   6 <html lang="en">
   7 <head>
   8   <meta charset="utf-8"  />
   9   <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"  />
  10   <title>MagickCore, C API: Morphological Erosions, Dilations, Openings, and Closings @ ImageMagick</title>
  11   <meta name="application-name" content="ImageMagick" />
  12   <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves." />
  13   <meta name="application-url" content="https://www.imagemagick.org" />
  14   <meta name="generator" content="PHP" />
  15   <meta name="keywords" content="magickcore, c, api:, morphological, erosions, dilations, openings, closings, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert" />
  16   <meta name="rating" content="GENERAL" />
  17   <meta name="robots" content="INDEX, FOLLOW" />
  18   <meta name="generator" content="ImageMagick Studio LLC" />
  19   <meta name="author" content="ImageMagick Studio LLC" />
  20   <meta name="revisit-after" content="2 DAYS" />
  21   <meta name="resource-type" content="document" />
  22   <meta name="copyright" content="Copyright (c) 1999-2018 ImageMagick Studio LLC" />
  23   <meta name="distribution" content="Global" />
  24   <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" />
  25   <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
  26   <link href="morphology.html" rel="canonical" />
  27   <link href="https://www.imagemagick.org/images/wand.png" rel="icon" />
  28   <link href="https://www.imagemagick.org/images/wand.ico" rel="shortcut icon" />
  29   <link href="https://www.imagemagick.org/css/magick.html" rel="stylesheet" />
  30 </head>
  31 <body>
  32 <div class="magick-masthead">
  33   <div class="container">
  34     <script async="async" src="https://localhost/pagead/js/adsbygoogle.js"></script>    <ins class="adsbygoogle"
  35          style="display:block"
  36          data-ad-client="ca-pub-3129977114552745"
  37          data-ad-slot="6345125851"
  38          data-ad-format="auto"></ins>
  39     <script>
  40       (adsbygoogle = window.adsbygoogle || []).push({});
  41     </script>
  42     <nav class="nav magick-nav">
  43       <a class="nav-link " href="https://www.imagemagick.org/index.html">Home</a>
  44       <a class="nav-link " href="https://www.imagemagick.org/script/download.html">Download</a>
  45       <a class="nav-link " href="https://www.imagemagick.org/script/command-line-tools.html">Tools</a>
  46       <a class="nav-link " href="https://www.imagemagick.org/script/command-line-processing.html">Command-line</a>
  47       <a class="nav-link " href="https://www.imagemagick.org/script/resources.html">Resources</a>
  48       <a class="nav-link " href="https://www.imagemagick.org/script/develop.html">Develop</a>
  49       <a class="nav-link " href="https://www.imagemagick.org/script/search.html">Search</a>
  50       <a class="nav-link float-right" href="https://www.imagemagick.org/discourse-server/">Community</a>
  51     </nav>
  52   </div>
  53 </div>
  54 <div class="container">
  55 <div class="magick-header">
  56 <p class="text-center"><a href="morphology.html#AcquireKernelInfo">AcquireKernelInfo</a> &#8226; <a href="morphology.html#AcquireKernelBuiltIn">AcquireKernelBuiltIn</a> &#8226; <a href="morphology.html#CloneKernelInfo">CloneKernelInfo</a> &#8226; <a href="morphology.html#DestroyKernelInfo">DestroyKernelInfo</a> &#8226; <a href="morphology.html#MorphologyApply">MorphologyApply</a> &#8226; <a href="morphology.html#This is almost identical to the MorphologyPrimative">This is almost identical to the MorphologyPrimative</a> &#8226; <a href="morphology.html#MorphologyImage">MorphologyImage</a> &#8226; <a href="morphology.html#ScaleGeometryKernelInfo">ScaleGeometryKernelInfo</a> &#8226; <a href="morphology.html#ScaleKernelInfo">ScaleKernelInfo</a> &#8226; <a href="morphology.html#ShowKernelInfo">ShowKernelInfo</a> &#8226; <a href="morphology.html#UnityAddKernelInfo">UnityAddKernelInfo</a> &#8226; <a href="morphology.html#ZeroKernelNans">ZeroKernelNans</a></p>
  57
  58 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="AcquireKernelInfo">AcquireKernelInfo</a></h2>
  59
  60 <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>
  61
  62 <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>
  63
  64 <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>
  65
  66 <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>
  67
  68 <p>The returned kernel should be freed using the DestroyKernelInfo() when you are finished with it.  Do not free this memory yourself.</p>
  69
  70 <p>Input kernel defintion strings can consist of any of three types.</p>
  71
  72 <p>"name:args[[@&gt;&lt;]" Select from one of the built in kernels, using the name and geometry arguments supplied.  See AcquireKernelBuiltIn()</p>
  73
  74 <p>"WxH[+X+Y][@&gt;&lt;]: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>
  75
  76 <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>
  77
  78 <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>
  79
  80 <p>" kernel ; kernel ; kernel ; "</p>
  81
  82 <p>Any extra ';' characters, at start, end or between kernel defintions are simply ignored.</p>
  83
  84 <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 '&gt;' will generate a list of 90-degree rotations. The '&lt;' 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>
  85
  86 <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>
  87
  88 <p>The format of the AcquireKernal method is:</p>
  89
  90 <pre class="text">
  91 KernelInfo *AcquireKernelInfo(const char *kernel_string)
  92 </pre>
  93
  94 <p>A description of each parameter follows:</p>
  95
  96 <dd>
  97 </dd>
  98
  99 <dd> </dd>
 100 <dl class="dl-horizontal">
 101 <dt>kernel_string</dt>
 102 <dd>the Morphology/Convolution kernel wanted. </dd>
 103
 104 <dd>  </dd>
 105 </dl>
 106 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="AcquireKernelBuiltIn">AcquireKernelBuiltIn</a></h2>
 107
 108 <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>
 109
 110 <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>
 111
 112 <p>The format of the AcquireKernalBuiltIn method is:</p>
 113
 114 <pre class="text">
 115 KernelInfo *AcquireKernelBuiltIn(const KernelInfoType type,
 116      const GeometryInfo args)
 117 </pre>
 118
 119 <p>A description of each parameter follows:</p>
 120
 121 <dd>
 122 </dd>
 123
 124 <dd> </dd>
 125 <dl class="dl-horizontal">
 126 <dt>type</dt>
 127 <dd>the pre-defined type of kernel wanted </dd>
 128
 129 <dd> </dd>
 130 <dt>args</dt>
 131 <dd>arguments defining or modifying the kernel </dd>
 132
 133 <dd> Convolution Kernels </dd>
 134
 135 <dd> Unity The a No-Op or Scaling single element kernel. </dd>
 136
 137 <dd> Gaussian:{radius},{sigma} Generate a two-dimensional gaussian kernel, as used by -gaussian. The sigma for the curve is required.  The resulting kernel is normalized, </dd>
 138
 139 <dd> If 'sigma' is zero, you get a single pixel on a field of zeros. </dd>
 140
 141 <dd> 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. </dd>
 142
 143 <dd> LoG:{radius},{sigma} "Laplacian of a Gaussian" or "Mexician Hat" Kernel. The supposed ideal edge detection, zero-summing kernel. </dd>
 144
 145 <dd> An alturnative to this kernel is to use a "DoG" with a sigma ratio of approx 1.6 (according to wikipedia). </dd>
 146
 147 <dd> 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 &gt; sigma1. The result is a zero-summing kernel. </dd>
 148
 149 <dd> 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. </dd>
 150
 151 <dd> If 'sigma' is zero, you get a single pixel on a field of zeros. </dd>
 152
 153 <dd> 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. </dd>
 154
 155 <dd> 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. </dd>
 156
 157 <dd> Note that the first argument is the width of the kernel and not the radius of the kernel. </dd>
 158
 159 <dd> Binomial:[{radius}] Generate a discrete kernel using a 2 dimentional Pascel's Triangle of values. Used for special forma of image filters. </dd>
 160
 161 <dd> # Still to be implemented... # # Filter2D # Filter1D #    Set kernel values using a resize filter, and given scale (sigma) #    Cylindrical or Linear.   Is this possible with an image? # </dd>
 162
 163 <dd> Named Constant Convolution Kernels </dd>
 164
 165 <dd> 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'. </dd>
 166
 167 <dd> 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. </dd>
 168
 169 <dd> 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) </dd>
 170
 171 <dd> Sobel:{angle} Sobel 'Edge' convolution kernel (3x3) | -1, 0, 1 | | -2, 0,-2 | | -1, 0, 1 | </dd>
 172
 173 <dd> Roberts:{angle} Roberts convolution kernel (3x3) |  0, 0, 0 | | -1, 1, 0 | |  0, 0, 0 | </dd>
 174
 175 <dd> Prewitt:{angle} Prewitt Edge convolution kernel (3x3) | -1, 0, 1 | | -1, 0, 1 | | -1, 0, 1 | </dd>
 176
 177 <dd> Compass:{angle} Prewitt's "Compass" convolution kernel (3x3) | -1, 1, 1 | | -1,-2, 1 | | -1, 1, 1 | </dd>
 178
 179 <dd> Kirsch:{angle} Kirsch's "Compass" convolution kernel (3x3) | -3,-3, 5 | | -3, 0, 5 | | -3,-3, 5 | </dd>
 180
 181 <dd> 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. </dd>
 182
 183 <dd> |   1,     0,   -1     | | sqrt(2), 0, -sqrt(2) | |   1,     0,   -1     | </dd>
 184
 185 <dd> FreiChen:{type},{angle} </dd>
 186
 187 <dd> Frei-Chen Pre-weighted kernels... </dd>
 188
 189 <dd> Type 0:  default un-nomalized version shown above. </dd>
 190
 191 <dd> Type 1: Orthogonal Kernel (same as type 11 below) |   1,     0,   -1     | | sqrt(2), 0, -sqrt(2) | / 2*sqrt(2) |   1,     0,   -1     | </dd>
 192
 193 <dd> Type 2: Diagonal form of Kernel... |   1,     sqrt(2),    0     | | sqrt(2),   0,     -sqrt(2) | / 2*sqrt(2) |   0,    -sqrt(2)    -1     | </dd>
 194
 195 <dd> 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. </dd>
 196
 197 <dd> Type 10: All 9 of the following pre-weighted kernels... </dd>
 198
 199 <dd> Type 11: |   1,     0,   -1     | | sqrt(2), 0, -sqrt(2) | / 2*sqrt(2) |   1,     0,   -1     | </dd>
 200
 201 <dd> Type 12: | 1, sqrt(2), 1 | | 0,   0,     0 | / 2*sqrt(2) | 1, sqrt(2), 1 | </dd>
 202
 203 <dd> Type 13: | sqrt(2), -1,    0     | |  -1,      0,    1     | / 2*sqrt(2) |   0,      1, -sqrt(2) | </dd>
 204
 205 <dd> Type 14: |    0,     1, -sqrt(2) | |   -1,     0,     1    | / 2*sqrt(2) | sqrt(2), -1,     0    | </dd>
 206
 207 <dd> Type 15: | 0, -1, 0 | | 1,  0, 1 | / 2 | 0, -1, 0 | </dd>
 208
 209 <dd> Type 16: |  1, 0, -1 | |  0, 0,  0 | / 2 | -1, 0,  1 | </dd>
 210
 211 <dd> Type 17: |  1, -2,  1 | | -2,  4, -2 | / 6 | -1, -2,  1 | </dd>
 212
 213 <dd> Type 18: | -2, 1, -2 | |  1, 4,  1 | / 6 | -2, 1, -2 | </dd>
 214
 215 <dd> Type 19: | 1, 1, 1 | | 1, 1, 1 | / 3 | 1, 1, 1 | </dd>
 216
 217 <dd> 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. </dd>
 218
 219 <dd> 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. </dd>
 220
 221 <dd> 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. </dd>
 222
 223 <dd> 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. </dd>
 224
 225 <dd> Boolean Kernels </dd>
 226
 227 <dd> 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. </dd>
 228
 229 <dd> Square:[{radius}[,{scale}]] Generate a square shaped kernel of size radius*2+1, and defaulting to a 3x3 (radius 1). </dd>
 230
 231 <dd> 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. </dd>
 232
 233 <dd> 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. </dd>
 234
 235 <dd> 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"    =&gt; "Diamond", "Octagon:1", or "Cross:1" "Disk:1.5"  =&gt; "Square" "Disk:2"    =&gt; "Diamond:2" "Disk:2.5"  =&gt; "Octagon" "Disk:2.9"  =&gt; "Square:2" "Disk:3.5"  =&gt; "Octagon:3" "Disk:4.5"  =&gt; "Octagon:4" "Disk:5.4"  =&gt; "Octagon:5" "Disk:6.4"  =&gt; "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. </dd>
 236
 237 <dd> 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. </dd>
 238
 239 <dd> Properly centered and odd sized rectangles work the best. </dd>
 240
 241 <dd> Symbol Dilation Kernels </dd>
 242
 243 <dd> 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. </dd>
 244
 245 <dd> For the same reasons iterating these kernels does not produce the same result as using a larger radius for the symbol. </dd>
 246
 247 <dd> 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). </dd>
 248
 249 <dd> NOTE: "plus:1" is equivalent to a "Diamond" kernel. </dd>
 250
 251 <dd> 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" -&gt; "Ring:2.5,3.5,1.0" </dd>
 252
 253 <dd> Hit and Miss Kernels </dd>
 254
 255 <dd> 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. </dd>
 256
 257 <dd> Distance Measuring Kernels </dd>
 258
 259 <dd> 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. </dd>
 260
 261 <dd> See the 'Distance' Morphological Method, for information of how it is applied. </dd>
 262
 263 <dd> 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. </dd>
 264
 265 <dd> 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. </dd>
 266
 267 <dd> 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. </dd>
 268
 269 <dd> 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. </dd>
 270
 271 <dd> 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. </dd>
 272
 273 <dd> 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. </dd>
 274
 275 <dd> The "Euclidean" Distance Kernel however does generate a non-integer fractional results, and as such scaling is vital even for binary shapes. </dd>
 276
 277 <dd>  </dd>
 278 </dl>
 279 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="CloneKernelInfo">CloneKernelInfo</a></h2>
 280
 281 <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>
 282
 283 <p>The format of the CloneKernelInfo method is:</p>
 284
 285 <pre class="text">
 286 KernelInfo *CloneKernelInfo(const KernelInfo *kernel)
 287 </pre>
 288
 289 <p>A description of each parameter follows:</p>
 290
 291 <dd>
 292 </dd>
 293
 294 <dd> </dd>
 295 <dl class="dl-horizontal">
 296 <dt>kernel</dt>
 297 <dd>the Morphology/Convolution kernel to be cloned </dd>
 298
 299 <dd>  </dd>
 300 </dl>
 301 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="DestroyKernelInfo">DestroyKernelInfo</a></h2>
 302
 303 <p>DestroyKernelInfo() frees the memory used by a Convolution/Morphology kernel.</p>
 304
 305 <p>The format of the DestroyKernelInfo method is:</p>
 306
 307 <pre class="text">
 308 KernelInfo *DestroyKernelInfo(KernelInfo *kernel)
 309 </pre>
 310
 311 <p>A description of each parameter follows:</p>
 312
 313 <dd>
 314 </dd>
 315
 316 <dd> </dd>
 317 <dl class="dl-horizontal">
 318 <dt>kernel</dt>
 319 <dd>the Morphology/Convolution kernel to be destroyed </dd>
 320
 321 <dd>  </dd>
 322 </dl>
 323 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="MorphologyApply">MorphologyApply</a></h2>
 324
 325 <p>MorphologyApply() applies a morphological method, multiple times using a list of multiple kernels.  This is the method that should be called by other 'operators' that internally use morphology operations as part of their processing.</p>
 326
 327 <p>It is basically equivalent to as MorphologyImage() (see below) but without any user controls.  This allows internel programs to use this method to perform a specific task without possible interference by any API user supplied settings.</p>
 328
 329 <p>It is MorphologyImage() task to extract any such user controls, and pass them to this function for processing.</p>
 330
 331 <p>More specifically all given kernels should already be scaled, normalised, and blended appropriatally before being parred to this routine. The appropriate bias, and compose (typically 'UndefinedComposeOp') given.</p>
 332
 333 <p>The format of the MorphologyApply method is:</p>
 334
 335 <pre class="text">
 336 Image *MorphologyApply(const Image *image,MorphologyMethod method,
 337   const ssize_t iterations,const KernelInfo *kernel,
 338   const CompositeMethod compose,const double bias,
 339   ExceptionInfo *exception)
 340 </pre>
 341
 342 <p>A description of each parameter follows:</p>
 343
 344 <dd>
 345 </dd>
 346
 347 <dd> </dd>
 348 <dl class="dl-horizontal">
 349 <dt>image</dt>
 350 <dd>the source image </dd>
 351
 352 <dd> </dd>
 353 <dt>method</dt>
 354 <dd>the morphology method to be applied. </dd>
 355
 356 <dd> </dd>
 357 <dt>iterations</dt>
 358 <dd>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. </dd>
 359
 360 <dd> </dd>
 361 <dt>channel</dt>
 362 <dd>the channel type. </dd>
 363
 364 <dd> </dd>
 365 <dt>kernel</dt>
 366 <dd>An array of double representing the morphology kernel. </dd>
 367
 368 <dd> </dd>
 369 <dt>compose</dt>
 370 <dd>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. </dd>
 371
 372 <dd> </dd>
 373 <dt>bias</dt>
 374 <dd>Convolution Output Bias. </dd>
 375
 376 <dd> </dd>
 377 <dt>exception</dt>
 378 <dd>return any errors or warnings in this structure. </dd>
 379
 380 <dd>  </dd>
 381 </dl>
 382 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="This_is almost identical to the MorphologyPrimative">This is almost identical to the MorphologyPrimative</a></h2>
 383
 384 <p>This is almost identical to the MorphologyPrimative() function above, but applies the primitive directly to the actual image using two passes, once in each direction, with the results of the previous (and current) row being re-used.</p>
 385
 386 <p>That is after each row is 'Sync'ed' into the image, the next row makes use of those values as part of the calculation of the next row.  It repeats, but going in the oppisite (bottom-up) direction.</p>
 387
 388 <p>Because of this 're-use of results' this function can not make use of multi- threaded, parellel processing. </p>
 389 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="MorphologyImage">MorphologyImage</a></h2>
 390
 391 <p>MorphologyImage() applies a user supplied kernel to the image according to the given mophology method.</p>
 392
 393 <p>This function applies any and all user defined settings before calling the above internal function MorphologyApply().</p>
 394
 395 <p>User defined settings include... * Output Bias for Convolution and correlation ("-define convolve:bias=??") * Kernel Scale/normalize settings            ("-define convolve:scale=??") This can also includes the addition of a scaled unity kernel. * Show Kernel being applied            ("-define morphology:showkernel=1")</p>
 396
 397 <p>Other operators that do not want user supplied options interfering, especially "convolve:bias" and "morphology:showkernel" should use MorphologyApply() directly.</p>
 398
 399 <p>The format of the MorphologyImage method is:</p>
 400
 401 <pre class="text">
 402 Image *MorphologyImage(const Image *image,MorphologyMethod method,
 403   const ssize_t iterations,KernelInfo *kernel,ExceptionInfo *exception)
 404 </pre>
 405
 406 <p>A description of each parameter follows:</p>
 407
 408 <dd>
 409 </dd>
 410
 411 <dd> </dd>
 412 <dl class="dl-horizontal">
 413 <dt>image</dt>
 414 <dd>the image. </dd>
 415
 416 <dd> </dd>
 417 <dt>method</dt>
 418 <dd>the morphology method to be applied. </dd>
 419
 420 <dd> </dd>
 421 <dt>iterations</dt>
 422 <dd>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. </dd>
 423
 424 <dd> </dd>
 425 <dt>kernel</dt>
 426 <dd>An array of double representing the morphology kernel. Warning: kernel may be normalized for the Convolve method. </dd>
 427
 428 <dd> </dd>
 429 <dt>exception</dt>
 430 <dd>return any errors or warnings in this structure. </dd>
 431
 432 <dd>  </dd>
 433 </dl>
 434 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ScaleGeometryKernelInfo">ScaleGeometryKernelInfo</a></h2>
 435
 436 <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>
 437
 438 <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>
 439
 440 <p>The format of the ScaleGeometryKernelInfo method is:</p>
 441
 442 <pre class="text">
 443 void ScaleGeometryKernelInfo(KernelInfo *kernel,
 444   const double scaling_factor,const MagickStatusType normalize_flags)
 445 </pre>
 446
 447 <p>A description of each parameter follows:</p>
 448
 449 <dd>
 450 </dd>
 451
 452 <dd> </dd>
 453 <dl class="dl-horizontal">
 454 <dt>kernel</dt>
 455 <dd>the Morphology/Convolution kernel to modify </dd>
 456
 457 <dd> o geometry: </dd>
 458
 459 <pre class="text">
 460        "-set option:convolve:scale {geometry}" setting.
 461 </pre>
 462
 463 <p></dd>
 464 </dl>
 465 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ScaleKernelInfo">ScaleKernelInfo</a></h2>
 466
 467 <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>
 468
 469 <p>By default (no flags given) the values within the kernel is scaled directly using given scaling factor without change.</p>
 470
 471 <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>
 472
 473 <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>
 474
 475 <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>
 476
 477 <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>
 478
 479 <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>
 480
 481 <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>
 482
 483 <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>
 484
 485 <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>
 486
 487 <p>The format of the ScaleKernelInfo method is:</p>
 488
 489 <pre class="text">
 490 void ScaleKernelInfo(KernelInfo *kernel, const double scaling_factor,
 491          const MagickStatusType normalize_flags )
 492 </pre>
 493
 494 <p>A description of each parameter follows:</p>
 495
 496 <dd>
 497 </dd>
 498
 499 <dd> </dd>
 500 <dl class="dl-horizontal">
 501 <dt>kernel</dt>
 502 <dd>the Morphology/Convolution kernel </dd>
 503
 504 <dd> o scaling_factor: </dd>
 505
 506 <pre class="text">
 507        zero.  If the kernel is normalized regardless of any flags.
 508 </pre>
 509
 510 <p>o normalize_flags: </dd>
 511
 512 <pre class="text">
 513        specifically: NormalizeValue, CorrelateNormalizeValue,
 514                      and/or PercentValue
 515 </pre>
 516
 517 <p></dd>
 518 </dl>
 519 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ShowKernelInfo">ShowKernelInfo</a></h2>
 520
 521 <p>ShowKernelInfo() outputs the details of the given kernel defination to standard error, generally due to a users 'morphology:showkernel' option request.</p>
 522
 523 <p>The format of the ShowKernel method is:</p>
 524
 525 <pre class="text">
 526 void ShowKernelInfo(const KernelInfo *kernel)
 527 </pre>
 528
 529 <p>A description of each parameter follows:</p>
 530
 531 <dd>
 532 </dd>
 533
 534 <dd> </dd>
 535 <dl class="dl-horizontal">
 536 <dt>kernel</dt>
 537 <dd>the Morphology/Convolution kernel </dd>
 538
 539 <dd>  </dd>
 540 </dl>
 541 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="UnityAddKernelInfo">UnityAddKernelInfo</a></h2>
 542
 543 <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>
 544
 545 <p>The resulting effect is to convert the defined kernels into blended soft-blurs, unsharp kernels or into sharpening kernels.</p>
 546
 547 <p>The format of the UnityAdditionKernelInfo method is:</p>
 548
 549 <pre class="text">
 550 void UnityAdditionKernelInfo(KernelInfo *kernel, const double scale )
 551 </pre>
 552
 553 <p>A description of each parameter follows:</p>
 554
 555 <dd>
 556 </dd>
 557
 558 <dd> </dd>
 559 <dl class="dl-horizontal">
 560 <dt>kernel</dt>
 561 <dd>the Morphology/Convolution kernel </dd>
 562
 563 <dd> o scale: </dd>
 564
 565 <pre class="text">
 566        the given kernel.
 567 </pre>
 568
 569 <p></dd>
 570 </dl>
 571 <h2><a href="http://www.imagemagick.org/api/MagickCore/morphology_8c.html" id="ZeroKernelNans">ZeroKernelNans</a></h2>
 572
 573 <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>
 574
 575 <p>The format of the ZeroKernelNans method is:</p>
 576
 577 <pre class="text">
 578 void ZeroKernelNans (KernelInfo *kernel)
 579 </pre>
 580
 581 <p>A description of each parameter follows:</p>
 582
 583 <dd>
 584 </dd>
 585
 586 <dd> </dd>
 587 <dl class="dl-horizontal">
 588 <dt>kernel</dt>
 589 <dd>the Morphology/Convolution kernel </dd>
 590
 591 <dd>  </dd>
 592 </dl>
 593 </div>
 594   <footer class="magick-footer">
 595     <p><a href="https://www.imagemagick.org/script/support.html">Donate</a> •
 596      <a href="https://www.imagemagick.org/script/sitemap.html">Sitemap</a> •
 597     <a href="https://www.imagemagick.org/script/links.html">Related</a> •
 598     <a href="https://www.imagemagick.org/script/security-policy.html">Security</a> •
 599     <a href="https://www.imagemagick.org/script/architecture.html">Architecture</a>
 600 </p>
 601     <p><a href="morphology.html#">Back to top</a> •
 602     <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
 603     <a href="https://www.imagemagick.org/script/contact.html">Contact Us</a></p>
 604         <p><small>© 1999-2018 ImageMagick Studio LLC</small></p>
 605   </footer>
 606 </div><!-- /.container -->
 607
 608   <script src="https://localhost/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
 609   <script src="https://www.imagemagick.org/js/magick.html"></script>
 610 </body>
 611 </html>