Processing
Options
Usage
MagickWand
MagickCore
PerlMagick
Magick++
Unix
Windows
Unix
Mac OS X
Windows
Links

## same variable That is the IsNaN

same variable That is the IsNaN() macro is only true if the value is NaN.

## AcquireKernelInfo

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.

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.

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.

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.

The returned kernel should be freed using the DestroyKernelInfo() when you are finished with it. Do not free this memory yourself.

Input kernel defintion strings can consist of any of three types.

"name:args" Select from one of the built in kernels, using the name and geometry arguments supplied. See AcquireKernelBuiltIn()

"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.

"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.

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.

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.

" kernel ; kernel ; kernel ; "

Extra ';' characters are simply ignored.

The format of the AcquireKernal method is:

      KernelInfo *AcquireKernelInfo(const char *kernel_string)

A description of each parameter follows:

##### kernel_string

the Morphology/Convolution kernel wanted.

## AcquireKernelBuiltIn

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.

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.

The format of the AcquireKernalBuiltIn method is:

      KernelInfo *AcquireKernelBuiltIn(const KernelInfoType type,
           const GeometryInfo args)

A description of each parameter follows:

##### type

the pre-defined type of kernel wanted

##### args

arguments defining or modifying the kernel

Convolution Kernels

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,

If 'sigma' is zero, you get a single pixel on a field of zeros.

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.

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.

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.

If 'sigma' is zero, you get a single pixel on a field of zeros.

Note that two convolutions with two "Blur" kernels perpendicular to each other, is equivelent 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.

DOB:{radius},{sigma1},{sigma2}[,{angle}] "Difference of Blurs" Kernel. As "Blur" but with the 1D gaussian produced by 'sigma2' subtracted from thethe 1D gaussian produced by 'sigma1'. The result is a zero-summing kernel.

This can be used to generate a faster "DOG" convolution, in the same way "Blur" can.

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.

Note that the first argument is the width of the kernel and not the radius of the kernel.

# 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? #

Named Constant Convolution Kernels

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'.

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.

Laplacian:{type} Generate Lapacian kernel of the type specified. (1 is the default) 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:-2 corner:1 Type 3 : 3x3 with center:4 edge:1 corner:-2 Type 4 : 5x5 laplacian Type 5 : 7x7 laplacian

Sobel:{angle} Sobel 3x3 'Edge' convolution kernel (3x3) -1, 0, 1 -2, 0,-2 -1, 0, 1 Roberts:{angle} Roberts 3x3 convolution kernel (3x3) 0, 0, 0 -1, 1, 0 0, 0, 0 Compass:{angle} Prewitt's "Compass" convolution kernel (3x3) -1, 1, 1 -1,-2, 1 -1, 1, 1 Prewitt:{angle} Prewitt Edge convolution kernel (3x3) -1, 0, 1 -1, 0, 1 -1, 0, 1

Boolean Kernels

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.

Square:[{radius}[,{scale}]] Generate a square shaped kernel of size radius*2+1, and defaulting to a 3x3 (radius 1).

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 iterating with the smaller radius is actually faster than using a larger kernel radius.

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.

Properly centered and odd sized rectangles work the best.

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.

Because a "disk" is more circular when using a larger radius, using a larger radius is preferred over iterating the morphological operation.

Symbol Dilation Kernels

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.

For the same reasons iterating these kernels does not produce the same result as using a larger radius for the symbol.

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).

NOTE: "plus:1" is equivelent to a "Diamond" kernel.

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"

Hit and Miss Kernels

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". 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

Distance Measuring Kernels

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.

See the 'Distance' Morphological Method, for information of how it is applied.

Chebyshev:[{radius}][x{scale}[!]] 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.

Manhatten:[{radius}][x{scale}[!]] 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.

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, which is reasonally accurate.

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.

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.

## CloneKernelInfo

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.

The format of the CloneKernelInfo method is:

      KernelInfo *CloneKernelInfo(const KernelInfo *kernel)

A description of each parameter follows:

##### kernel

the Morphology/Convolution kernel to be cloned

## DestroyKernelInfo

DestroyKernelInfo() frees the memory used by a Convolution/Morphology kernel.

The format of the DestroyKernelInfo method is:

      KernelInfo *DestroyKernelInfo(KernelInfo *kernel)

A description of each parameter follows:

##### kernel

the Morphology/Convolution kernel to be destroyed

## ExpandKernelInfo

ExpandKernelInfo() takes a single kernel, and expands it into a list of kernels each incrementally rotated the angle given.

WARNING: 45 degree rotations only works for 3x3 kernels. While 90 degree roatations only works for linear and square kernels

The format of the RotateKernelInfo method is:

      void ExpandKernelInfo(KernelInfo *kernel, double angle)

A description of each parameter follows:

##### kernel

the Morphology/Convolution kernel

##### angle

angle to rotate in degrees

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.

## MorphologyImageChannel

MorphologyImageChannel() applies a user supplied kernel to the image according to the given mophology method.

The given kernel is assumed to have been pre-scaled appropriatally, usally by the kernel generator.

The format of the MorphologyImage method is:

      Image *MorphologyImage(const Image *image,MorphologyMethod method,
        const long iterations,KernelInfo *kernel,ExceptionInfo *exception)
      Image *MorphologyImageChannel(const Image *image, const ChannelType
        channel,MorphologyMethod method,const long iterations,
        KernelInfo *kernel,ExceptionInfo *exception)

A description of each parameter follows:

##### image

the image.

##### method

the morphology method to be applied.

##### iterations

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.

##### channel

the channel type.

##### kernel

An array of double representing the morphology kernel. Warning: kernel may be normalized for the Convolve method.

##### exception

return any errors or warnings in this structure.

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.

## ScaleKernelInfo

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).

By default (no flags given) the values within the kernel is scaled directly using given scaling factor without change.

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.

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.

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.

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.

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.

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.

WARNING: Correct normalization of the kernel assumes that the '*_range' attributes within the kernel structure have been correctly set during the kernels creation.

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.

The format of the ScaleKernelInfo method is:

      void ScaleKernelInfo(KernelInfo *kernel, const double scaling_factor,
               const MagickStatusType normalize_flags )

A description of each parameter follows:

##### kernel

the Morphology/Convolution kernel

o scaling_factor:

             zero.  If the kernel is normalized regardless of any flags.

o normalize_flags:

             specifically: NormalizeValue, CorrelateNormalizeValue,
                           and/or PercentValue

This function is internal to this module only at this time, but can be exported to other modules if needed.

Discourse Server • Studio