NAME

effects - ImageMagick Image Effects Methods

SYNOPSIS

Image * AddNoiseImage( Image *image, const NoiseType noise_type, ExceptionInfo *exception );

Image * BlurImage( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

Image * ColorizeImage( Image *image, const char *opacity, const PixelPacket target, ExceptionInfo *exception );

Image * ConvolveImage( Image *image, const unsigned int order, const double *kernel, ExceptionInfo *exception );

Image * DespeckleImage( Image *image, ExceptionInfo *exception );

Image * EdgeImage( Image *image, const double radius, ExceptionInfo *exception );

Image * EmbossImage( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

Image * EnhanceImage( Image *image, ExceptionInfo *exception );

Image * GaussianBlurImage( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

Image * ImplodeImage( Image *image, const double factor, ExceptionInfo *exception );

Image * MedianFilterImage( Image *image, const double radius, ExceptionInfo *exception );

Image * MorphImages( Image *image, const unsigned int number_frames, ExceptionInfo *exception );

Image * OilPaintImage( Image *image, const double radius, ExceptionInfo *exception );

unsigned int PlasmaImage( Image *image, const SegmentInfo *segment, int attenuate, int depth );

Image * ReduceNoiseImage( Image *image, const double, ExceptionInfo *exception );

Image * ShadeImage( Image *image, const unsigned int color_shading, double azimuth, double elevation, ExceptionInfo *exception );

Image * SharpenImage( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

void SolarizeImage( Image *image, const double factor );

Image * SpreadImage( Image *image, const unsigned int amount, ExceptionInfo *exception );

Image * SteganoImage( Image *image, Image *watermark, ExceptionInfo *exception );

Image * StereoImage( Image *image, Image *offset_image, ExceptionInfo *exception );

Image * SwirlImage( Image *image, double degrees, ExceptionInfo *exception );

unsigned int ThresholdImage( Image *image, const double threshold );

Image * UnsharpMaskImage( Image *image, const double radius, const double sigma, const double amount, const double threshold, ExceptionInfo *exception );

Image * WaveImage( Image *image, const double amplitude, const double wave_length, ExceptionInfo *exception );

FUNCTION DESCRIPTIONS

AddNoiseImage

Method AddNoiseImage creates a new image that is a copy of an existing one with noise added. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the AddNoiseImage method is:

Image *AddNoiseImage ( Image *image, const NoiseType noise_type, ExceptionInfo *exception );

A description of each parameter follows:

noise_image:
Method AddNoiseImage returns a pointer to the image after the noise is minified. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

noise_type:
The type of noise: Gaussian, multiplicative Gaussian, impulse, laplacian, or Poisson.

exception:
return any errors or warnings in this structure.

BlurImage

Method BlurImage creates a blurred copy of the input image. We convolve the image with a Gaussian operator of the given width and standard deviation (sigma).

Each output pixel is set to a value that is the weighted average of the input pixels in an area enclosing the pixel. The width parameter determines how large the area is. Each pixel in the area is weighted in the average according to its distance from the center, and the standard deviation, sigma. The actual weight is calculated according to the Gaussian distribution (also called normal distribution), which looks like a Bell Curve centered on a pixel. The standard deviation controls how 'pointy' the curve is. The pixels near the center of the curve (closer to the center of the area we are averaging) contribute more than the distant pixels.

In general, the width should be wide enough to include most of the total weight under the Gaussian for the standard deviation you choose. the width parameter to the function specifies the radius of the Gaussian convolution mask in pixels, not counting the centre pixel, the width parameter should be chosen larger than the standard deviation, perhaps about twice as large to three times as large. A width of 1 will give a (standard) 3x3 convolution mask, a width of 2 gives a 5 by 5 convolution mask. Using non-integral widths will result in some pixels being considered 'partial' pixels, in which case their weight will be reduced proportionally.

Pixels for which the convolution mask does not completely fit on the image (e.g. pixels without a full set of neighbours) are averaged with those neighbours they do have. Thus pixels at the edge of images are typically less blur.

Since a 2d Gaussian is seperable, we perform the Gaussian blur by convolving with two 1d Gaussians, first in the x, then in the y direction. For an n by n image and Gaussian width w this requires 2wn^2 multiplications, while convolving with a 2d Gaussian requres w^2n^2 mults.

We blur the image into a copy, and the original is left untouched. We must process the image in two passes, in each pass we change the pixel based on its neighbors, but we need the pixel's original value for the next pixel's calculation. For the first pass we could use the original image but that's no good for the second pass, and it would imply that the original image have to stay around in ram. Instead we use a small (size=width) buffer to store the pixels we have overwritten.

This method was contributed by runger@cs.mcgill.ca.

The format of the BlurImage method is:

Image *BlurImage ( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

A description of each parameter follows:

blur_image:
Method BlurImage returns a pointer to the image after it is blur. A null image is returned if there is a memory shortage.

radius:
The radius of the Gaussian, in pixels, not counting the center pixel.

sigma:
The standard deviation of the Gaussian, in pixels.

exception:
return any errors or warnings in this structure.

ColorizeImage

Method ColorizeImage creates a new image that is a copy of an existing one with the image pixels colorized. The colorization is controlled with the pen color and the opacity levels.

The format of the ColorizeImage method is:

Image *ColorizeImage ( Image *image, const char *opacity, const PixelPacket target, ExceptionInfo *exception );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

opacity:
A character string indicating the level of opacity as a percentage (0-100).

target:
A color value.

exception:
return any errors or warnings in this structure.

ConvolveImage

Method ConvolveImage applies a general image convolution kernel to an image returns the results. ConvolveImage allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the ConvolveImage method is:

Image *ConvolveImage ( Image *image, const unsigned int order, const double *kernel, ExceptionInfo *exception );

A description of each parameter follows:

convolve_image:
Method ConvolveImage returns a pointer to the image after it is convolved. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

order:
The number of columns and rows in the filter kernel.

kernel:
An array of double representing the convolution kernel.

exception:
return any errors or warnings in this structure.

DespeckleImage

Method DespeckleImage creates a new image that is a copy of an existing one with the speckle noise minified. It uses the eight hull algorithm described in Applied Optics, Vol. 24, No. 10, 15 May 1985, ``Geometric filter for Speckle Reduction'', by Thomas R Crimmins. Each pixel in the image is replaced by one of its eight of its surrounding pixels using a polarity and negative hull function. DespeckleImage allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the DespeckleImage method is:

Image *DespeckleImage ( Image *image, ExceptionInfo *exception );

A description of each parameter follows:

despeckle_image:
Method DespeckleImage returns a pointer to the image after it is despeckled. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

exception:
return any errors or warnings in this structure.

EdgeImage

Method EdgeImage creates a new image that is a copy of an existing one with the edges enhanced. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the EdgeImage method is:

Image *EdgeImage ( Image *image, const double radius, ExceptionInfo *exception );

A description of each parameter follows:

edge_image:
Method EdgeImage returns a pointer to the image after it is edge. A null image is returned if there is a memory shortage.

image:
the address of a structure of type Image; returned from ReadImage.

radius:
the radius of the pixel neighborhood.

exception:
return any errors or warnings in this structure.

EmbossImage

Method EmbossImage creates a new image that is a copy of an existing one with the edge highlighted. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the EmbossImage method is:

Image *EmbossImage ( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

A description of each parameter follows:

emboss_image:
Method EmbossImage returns a pointer to the image after it is embossed. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

radius:
the radius of the pixel neighborhood.

sigma:
The standard deviation of the Gaussian, in pixels.

exception:
return any errors or warnings in this structure.

EnhanceImage

Method EnhanceImage creates a new image that is a copy of an existing one with the noise minified. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

EnhanceImage does a weighted average of pixels in a 5x5 cell around each target pixel. Only pixels in the 5x5 cell that are within a RGB distance threshold of the target pixel are averaged.

Weights assume that the importance of neighboring pixels is negately proportional to the square of their distance from the target pixel.

The scan only processes pixels that have a full set of neighbors. Pixels in the top, bottom, left, and right pairs of rows and columns are omitted from the scan.

The format of the EnhanceImage method is:

Image *EnhanceImage ( Image *image, ExceptionInfo *exception );

A description of each parameter follows:

enhance_image:
Method EnhanceImage returns a pointer to the image after it is enhanced. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

exception:
return any errors or warnings in this structure.

GaussianBlurImage

Method GaussianBlurImage creates a new image that is a copy of an existing one with the pixels blur. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the BlurImage method is:

Image *GaussianBlurImage ( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

A description of each parameter follows:

blur_image:
Method GaussianBlurImage returns a pointer to the image after it is blur. A null image is returned if there is a memory shortage.

radius:
the radius of the Gaussian, in pixels, not counting the center pixel.

sigma:
the standard deviation of the Gaussian, in pixels.

exception:
return any errors or warnings in this structure.

ImplodeImage

Method ImplodeImage creates a new image that is a copy of an existing one with the image pixels ``implode'' by the specified percentage. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the ImplodeImage method is:

Image *ImplodeImage ( Image *image, const double factor, ExceptionInfo *exception );

A description of each parameter follows:

implode_image:
Method ImplodeImage returns a pointer to the image after it is implode. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

factor:
A double value that defines the extent of the implosion.

exception:
return any errors or warnings in this structure.

MedianFilterImage

Method MedianFilterImage creates a new image that is a copy of an existing one with each pixel component replaced with the median color in a pixel neighborhood.

The format of the MedianFilterImage method is:

Image *MedianFilterImage ( Image *image, const double radius, ExceptionInfo *exception );

A description of each parameter follows:

median_image:
Method MedianFilterImage returns a pointer to the image after it is `filtered'. A null image is returned if there is a memory shortage.

image:
the address of a structure of type Image; returned from ReadImage.

radius:
the radius of the pixel neighborhood.

exception:
return any errors or warnings in this structure.

MorphImages

Method MorphImages morphs a sequence of images. Both the next pixels and size are linearly interpolated to give the appearance of a meta-morphosis from one next to the next.

The format of the MorphImage method is:

Image *MorphImages ( Image *image, const unsigned int number_frames, ExceptionInfo *exception );

A description of each parameter follows:

morph_images:
Method MorphImages returns an next sequence that has linearly interpolated pixels and size between two input image.

image:
The address of a structure of type Image; returned from ReadImage.

number_frames:
This unsigned integer reflects the number of in-between image to generate. The more in-between frames, the smoother the morph.

exception:
return any errors or warnings in this structure.

OilPaintImage

Method OilPaintImage creates a new image that is a copy of an existing one with each pixel component replaced with the color of greatest frequency in a circular neighborhood.

The format of the OilPaintImage method is:

Image *OilPaintImage ( Image *image, const double radius, ExceptionInfo *exception );

A description of each parameter follows:

paint_image:
Method OilPaintImage returns a pointer to the image after it is `painted'. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

radius:
The radius of the circular neighborhood.

exception:
return any errors or warnings in this structure.

PlasmaImage

Method PlasmaImage initializes an image with plasma fractal values. The image must be initialized with a base color and the random number generator seeded before this method is called.

The format of the PlasmaImage method is:

unsigned int PlasmaImage ( Image *image, const SegmentInfo *segment, int attenuate, int depth );

A description of each parameter follows:

status:
Method PlasmaImage returns True when the fractal process is complete. Otherwise False is returned.

image:
The address of a structure of type Image; returned from ReadImage.

segment:
specifies a structure of type SegmentInfo that defines the boundaries of the area where the plasma fractals are applied.

attenuate:
specifies the plasma attenuation factor.

depth:
this integer values define the plasma recursion depth.

ReduceNoiseImage

Method ReduceNoiseImage creates a new image that is a copy of an existing one with the noise minified with a noise peak elimination filter. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The principal function of noise peak elimination filter is to smooth the objects within an image without losing edge information and without creating undesired structures. The central idea of the algorithm is to replace a pixel with its next neighbor in value within a window, if this pixel has been found to be noise. A pixel is defined as noise if and only if this pixel is a maximum or minimum within the window.

The format of the ReduceNoiseImage method is:

Image *ReduceNoiseImage ( Image *image, const double, ExceptionInfo *exception );

A description of each parameter follows:

noise_image:
Method ReduceNoiseImage returns a pointer to the image after the noise is minified. A null image is returned if there is a memory shortage.

image:
the address of a structure of type Image; returned from ReadImage.

radius:
the radius of the pixel neighborhood.

exception:
return any errors or warnings in this structure.

ShadeImage

Method ShadeImage creates a new image that is a copy of an existing one with the image pixels shaded using a distance light source. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the ShadeImage method is:

Image *ShadeImage ( Image *image, const unsigned int color_shading, double azimuth, double elevation, ExceptionInfo *exception );

A description of each parameter follows:

shade_image:
Method ShadeImage returns a pointer to the image after it is shaded. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

color_shading:
A value other than zero shades the red, green, and blue components of the image.

azimuth, elevation:
A double value that indicates the light source direction.

exception:
return any errors or warnings in this structure.

SharpenImage

Method SharpenImage creates a new image that is sharpened version of the original image using a Laplacian convolution kernel.

The format of the SharpenImage method is:

Image *SharpenImage ( Image *image, const double radius, const double sigma, ExceptionInfo *exception );

A description of each parameter follows:

sharp_image:
Method SharpenImage returns a pointer to the image after it is sharp. A null image is returned if there is a memory shortage.

radius:
The radius of the Gaussian, in pixels, not counting the center pixel.

sigma:
The standard deviation of the Laplacian, in pixels.

exception:
return any errors or warnings in this structure.

SolarizeImage

Method SolarizeImage produces a 'solarization' effect seen when exposing a photographic film to light during the development process.

The format of the SolarizeImage method is:

void SolarizeImage ( Image *image, const double factor );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

factor:
An double value that defines the extent of the solarization.

SpreadImage

Method SpreadImage creates a new image that is a copy of an existing one with the image pixels randomly displaced. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the SpreadImage method is:

Image *SpreadImage ( Image *image, const unsigned int amount, ExceptionInfo *exception );

A description of each parameter follows:

spread_image:
Method SpreadImage returns a pointer to the image after it is spread. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

amount:
An unsigned value constraining the ``vicinity'' for choosing a random pixel to swap.

exception:
return any errors or warnings in this structure.

SteganoImage

Method SteganoImage hides a digital watermark within the image.

The format of the SteganoImage method is:

Image *SteganoImage ( Image *image, Image *watermark, ExceptionInfo *exception );

A description of each parameter follows:

stegano_image:
Method SteganoImage returns a pointer to the steganographic image with the watermark hidden. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image.

watermark:
The address of a structure of type Image.

exception:
return any errors or warnings in this structure.

StereoImage

Method StereoImage combines two images and produces a single image that is the composite of a left and right image of a stereo pair. The left image is converted to gray scale and written to the red channel of the stereo image. The right image is converted to gray scale and written to the blue channel of the stereo image. View the composite image with red-blue glasses to create a stereo effect.

The format of the StereoImage method is:

Image *StereoImage ( Image *image, Image *offset_image, ExceptionInfo *exception );

A description of each parameter follows:

stereo_image:
Method StereoImage returns a pointer to the stereo image. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image.

offset_image:
The address of a structure of type Image.

exception:
return any errors or warnings in this structure.

SwirlImage

Method SwirlImage creates a new image that is a copy of an existing one with the image pixels ``swirl'' at a specified angle. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the SwirlImage method is:

Image *SwirlImage ( Image *image, double degrees, ExceptionInfo *exception );

A description of each parameter follows:

swirl_image:
Method SwirlImage returns a pointer to the image after it is swirl. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

degrees:
An double value that defines the tightness of the swirling.

exception:
return any errors or warnings in this structure.

ThresholdImage

Method ThresholdImage thresholds the reference image.

The format of the ThresholdImage method is:

unsigned int ThresholdImage ( Image *image, const double threshold );

A description of each parameter follows:

image:
The address of a structure of type Image; returned from ReadImage.

threshold:
A double indicating the threshold value.

UnsharpMaskImage

Method UnsharpMaskImage creates a new image that is sharpened version of the original image using the unsharp mask algorithm.

The format of the UnsharpMaskImage method is:

Image *UnsharpMaskImage ( Image *image, const double radius, const double sigma, const double amount, const double threshold, ExceptionInfo *exception );

A description of each parameter follows:

unsharp_image:
Method UnsharpMaskImage returns a pointer to the image after it is blur. A null image is returned if there is a memory shortage.

radius:
The radius of the Gaussian, in pixels, not counting the center pixel.

sigma:
The standard deviation of the Gaussian, in pixels.

amount:
The percentage of the difference between the original and the blur image that is added back into the original.

threshold:
The threshold in pixels needed to apply the diffence amount.

exception:
return any errors or warnings in this structure.

WaveImage

Method WaveImage creates a new image that is a copy of an existing one with the image pixels altered along a sine wave. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

The format of the WaveImage method is:

Image *WaveImage ( Image *image, const double amplitude, const double wave_length, ExceptionInfo *exception );

A description of each parameter follows:

wave_image:
Method WaveImage returns a pointer to the image after it is waved. A null image is returned if there is a memory shortage.

image:
The address of a structure of type Image; returned from ReadImage.

amplitude, frequency:
A double value that indicates the amplitude and wave_length of the sine wave.

exception:
return any errors or warnings in this structure.