<< mkfilter SIP - Scilab Image Processing Toolbox normal >>

SIP - Scilab Image Processing Toolbox >> SIP - Scilab Image Processing Toolbox > mogrify

mogrify

Filter, rotate, zoom, equalize, and much more image manipulation.

Calling Sequence

[imout (,map)] = mogrify(im, argv)
[imout (,map)] = mogrify(imRGB, argv)
[imout (,map)] = mogrify(index, colormap, argv)

Input Parameters

im
binary or grayscale image in the 0-1 range
imRGB
truecolor image represented as a 3D array, in the 0-1 range.
index
MxN matrix containing the indexes to a colormap (for indexed images). Indices start at 1.
colormap

an (NCx3) matrix in the 0-1 range.

argv

(argument vector), a string vector, row or column, containing image processing commands. See the section "Argv Argument" bellow for a listing of the available options. The "Example" bellow demonstrates how to use this argument.

Output Parameters

imout
For truecolor images, this is a MxNx3 matrix in the 0-1 range. For binary images, image is a MxNx1 matrix (0=black and 1=white). For grayscale images, this is an MxN matrix in the 0-1 range. For indexed images, this is an MxN matrix in the 1-NC range, where NC is the number of colors.
map
NCx3 matrix containing the image colormap, where Nc is the number of colors. Entries range from 0 to 1.

Description

mogrify does many image processing operations. It is a direct C-language interface to ImageMagick, providing the same functinality as the commandline "mogrify" utilty. The difference is that SIP's mogrify acts upon scilab matrices instead of image files, and, therefore, is considerably faster. Please see the section "ARGV ARGUMENT" bellow for details on how the parameter argv is built.

Examples

Please follow the TransMogrify demo using the following command:
     exec(SIPDEMO);

The ARGV parameter

In this section, angle brackets ("<>") enclose variables and curly brackets ("{}") enclose optional parameters. For example, "-fuzz <distance>{%}" means you can use the option ['-fuzz','10'] or ['-fuzz', '2%'].

-affine <matrix>
drawing transform matrix. This option provides a transform matrix {sx,rx,ry,sy,tx,ty} for use by subsequent -draw or -transform option.
-antialias
remove pixel aliasing By default antialiasing algorithms are used when drawing objects (e.g. lines) or rendering vector formats (e.g. WMF and Postscript). Use +antialias to disable use of antialiasing algorithms. Reasons to disable antialiasing include avoiding increasing colors in the image, or improving rendering speed.
-background <color>
the background color The color is specified using the format described in the "Color Names" section of X(1).
-blur <radius>x<sigma>
blur the image with a Gaussian operator Blur with the given radius and standard deviation (sigma). It is better if the radius be greater than sigma, but the larger it is, the slower is the processing. If a radius equal to 0 is passed, then mogrify uses the optimal radius.
-border <width>x<height>
surround the image with a border of color See -geometry for details about the geometry specification.
-bordercolor <color>
the border color The color is specified using the format described in the "Color Names" section of X(1).
-channel <type>

the type of channel Choose from: Red, Green, Blue, Cyan, Magenta, Yellow, or Black.

Use this option to extract a particular channel from the image.

-charcoal <factor>
simulate a charcoal drawing
-colorize <value>
colorize the image with the pen color Specify the amount of colorization as a percentage. You can apply separate colorization values to the red, green, and blue channels of the image with a colorization value list delineated with slashes (e.g. 0/0/50).
-colorspace <value>

the type of colorspace Choices are: GRAY, OHTA, RGB, Transparent, XYZ, YCbCr, YIQ, YPbPr, YUV, or CMYK.

Color reduction, by default, takes place in the RGB color space. Empirical evidence suggests that distances in color spaces such as YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. These color spaces may give better results when color reducing an image. Refer to quantize for more details.

The Transparent color space behaves uniquely in that it preserves the matte channel of the image if it exists.

The -colors or -monochrome option is required for this option to take effect.

-contrast
enhance or reduce the image contrast This option enhances the intensity differences between the lighter and darker elements of the image. Use -contrast to enhance the image or +contrast to reduce the image contrast.
-crop <width>x<height>{+-}<x>{+-}<y>{%}

preferred size and location of the cropped image See -geometry for details about the geometry specification.

The width and height give the size of the image that remains after cropping, and x and y are offsets that give the location of the top left corner of the cropped image with respect to the original image. To specify the amount to be removed, use -shave instead.

To specify a percentage width or height to be removed instead, append %. For example to crop the image by ten percent (five percent on each side of the image), use -crop 10%.

If the x and y offsets are present, a single image is generated, consisting of the pixels from the cropping region. The offsets specify the location of the upper left corner of the cropping region measured downward and rightward with respect to the upper left corner of the image. If the -gravity option is present with NorthEast, East, or SouthEast gravity, it gives the distance leftward from the right edge of the image to the right edge of the cropping region. Similarly, if the -gravity option is present with SouthWest, South, or SouthEast gravity, the distance is measured upward between the bottom edges.

If the x and y offsets are omitted, a set of tiles of the specified geometry, covering the entire input image, is generated. The rightmost tiles and the bottom tiles are smaller if the specified geometry extends beyond the dimensions of the input image.

-cycle <amount>
displace image colormap by amount Amount defines the number of positions each colormap entry is shifted.
-debug enable debug printout
-despeckle reduce the speckles within an image
-dither

apply Floyd/Steinberg error diffusion to the image The basic strategy of dithering is to trade intensity resolution for spatial resolution by averaging the intensities of several neighboring pixels. Images which suffer from severe contouring when reducing colors can be improved with this option.

The -colors or -monochrome option is required for this option to take effect.

Use +dither to turn off dithering and to render PostScript without text or graphic aliasing.

-draw <string>

annotate an image with one or more graphic primitives Use this option to annotate an image with one or more graphic primitives. The primitives include shapes, text, transformations, and pixel operations. The shape primitives are

point x,y line x0,y0 x1,y1 rectangle x0,y0 x1,y1 roundRectangle x0,y0 x1,y1 wc,hc arc x0,y0 x1,y1 a0,a1 ellipse x0,y0 rx,ry a0,a1 circle x0,y0 x1,y1 polyline x0,y0 ... xn,yn polygon x0,y0 ... xn,yn Bezier x0,y0 ... xn,yn path path specification image operator x0,y0 w,h filename

The text primitive is

text x0,y0 string

The transformation primitives are

rotate degrees translate dx,dy scale sx,sy skewX degrees skewY degrees

The pixel operation primitives are

color x0,y0 method

The shape primitives are drawn in the color specified in the preceding -stroke option. Except for the line and point primitives, they are filled with the color specified in the preceding -fill option. For unfilled shapes, use -fill none.

Point requires a single coordinate.

Line requires a start and end coordinate.

Rectangle expects an upper left and lower right coordinate.

RoundRectangle has the upper left and lower right coordinates and the width and height of the corners.

Circle has a center coordinate and a coordinate for the outer edge.

Use Arc to circumscribe an arc within a rectangle. Arcs require a start and end point as well as the degree of rotation (e.g. 130,30 200,100 45,90).

Use Ellipse to draw a partial ellipse centered at the given point with the x-axis and y-axis radius and start and end of arc in degrees (e.g. 100,100 100,150 0,360).

Finally, polyline and polygon require three or more coordinates to define its boundaries. Coordinates are integers separated by an optional comma. For example, to define a circle centered at 100,100 that extends to 150,150 use:

['-draw'; 'circle 100,100 150,150']

Paths (See Paths) represent an outline of an object which is defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a curve using a cubic Bezier), arc (elliptical or circular arc) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by one or more line or curve operations) are possible to allow effects such as "donut holes" in objects.

Use image to composite an image with another image. Follow the image keyword with the composite operator, image location, image size, and filename:

['-draw'; 'image Over 100,100 225,225 image.jpg']

You can use 0,0 for the image size, which means to use the actual dimensions found in the image header. Otherwise, it will be scaled to the given dimensions.

Use text to annotate an image with text. Follow the text coordinates with a string. If the string has embedded spaces, enclose it in double quotes. Optionally you can include the image filename, type, width, height, or other image attribute by embedding special format character. See -comment for details.

For example,

['-draw'; 'text 100,100 ""%wx%h""']

annotates the image with 512x480 for an image whose width is 512 and height is 480.

If the first character of string is @, the text is read from a file titled by the remaining characters in the string.

Rotate rotates subsequent shape primitives and text primitives about the origin of the main image. If the -region option precedes the -draw option, the origen for transformations is the upper left corner of the region.

Translate translates them.

Scale scales them.

SkewX and SkewY skew them with respect to the origen of the main image or the region.

The transformations modify the current affine matrix, which is initialized from the initial affine matrix defined by the -affine option. Transformations are cumulative within the -draw option. The initial affine matrix is not affected; that matrix is only changed by the appearance of another -affine option. If another -draw option appears, the current affine matrix is reinitialized from the initial affine matrix.

Use color to change the color of a pixel to the fill color (see -fill). Follow the pixel coordinate with a method:

point replace floodfill filltoborder reset

Consider the target pixel as that specified by your coordinate. The point method recolors the target pixel. The replace method recolors any pixel that matches the color of the target pixel. Floodfill recolors any pixel that matches the color of the target pixel and is a neighbor, whereas filltoborder recolors any neighbor pixel that is not the border color. Finally, reset recolors all pixels.

You can set the primitive color, font, and font bounding box color with -fill, -font, and -box respectively. Options are processed in the argv order so be sure to use these options before the -draw option.

-edge <radius> detect edges within an image
-emboss emboss an image
-encoding <type>
specify the text encoding Choose from AdobeCustom, AdobeExpert, AdobeStandard, AppleRoman, BIG5, GB2312, Latin 2, None, SJIScode, Symbol, Unicode, Wansung.
-enhance apply a digital filter to enhance a noisy image
-equalize perform histogram equalization to the image
-fill <color>

color to use when filling a graphic primitive The color is specified using the format described in the "Color Names" section of X(1).

See -draw for further details.

-filter <type>

use this type of filter when resizing an image Use this option to affect the resizing operation of an image (see -geometry). Choose from these filters:

Point Box Triangle Hermite Hanning Hamming Blackman Gaussian Quadratic Cubic Catrom Mitchell Lanczos Bessel Sinc

The default filter is Lanczos

-flip
create a "mirror image" reflect the scanlines in the vertical direction.
-flop
create a "mirror image" reflect the scanlines in the horizontal direction.
-font <name>
use this font when annotating the image with text You can tag a font to specify whether it is a PostScript, TrueType, or OPTION1 font. For example, Arial.ttf is a TrueType font, ps:helvetica is PostScript, and x:fixed is OPTION1.
-foreground <color>
define the foreground color The color is specified using the format described in the "Color Names" section of X(1).
-frame <width>x<height>+<outer bevel width>+<inner bevel width>

surround the image with an ornamental border See -geometry for details about the geometry specification. The -frame option is not affected by the -gravity option.

The color of the border is specified with the -mattecolor command line option.

-frame include the X window frame in the imported image
-fuzz <distance>{%}

colors within this distance are considered equal A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space. For example, if you want to automatically trim the edges of an image with -trim but the image was scanned and the target background color may differ by a small amount. This option can account for these differences.

The distance can be in absolute intensity units or, by appending "%", as a percentage of the maximum possible intensity.

-gamma <value>

level of gamma correction The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference. Reasonable values extend from 0.8 to 2.3.

You can apply separate gamma values to the red, green, and blue channels of the image with a gamma value list delineated with slashes (e.g., 1.7/2.3/1.2).

-Gaussian <radius>x<sigma>
blur the image with a Gaussian operator Use the given radius and standard deviation (sigma).
-geometry <width>x<height>{+-}<x>{+-}<y>{%}{@} {!}{<}{>}

preferred size and location of the Image window. By default, the window size is the image size and the location is chosen by you when it is mapped.

By default, the width and height are maximum values. That is, the image is expanded or contracted to fit the width and height value while maintaining the aspect ratio of the image. Append an exclamation point to the geometry to force the image size to exactly the size you specify. For example, if you specify 640x480! the image width is set to 640 pixels and height to 480.

If only the width is specified, the width assumes the value and the height is chosen to maintain the aspect ratio of the image. Similarly, if only the height is specified (e.g., -geometry x256), the width is chosen to maintain the aspect ratio.

To specify a percentage width or height instead, append %. The image size is multiplied by the width and height percentages to obtain the final image dimensions. To increase the size of an image, use a value greater than 100 (e.g. 125%). To decrease an image's size, use a percentage less than 100.

Use @ to specify the maximum area in pixels of an image.

Use > to change the dimensions of the image only if its width or height exceeds the geometry specification. < resizes the image only if both of its dimensions are less than the geometry specification. For Example, if you specify '640x480>' and the image size is 256x256, the image size does not change. However, if the image is 512x512 or 1024x1024, it is resized to 480x480. Enclose the geometry specification in quotation marks to prevent the < or > from being interpreted by your shell as a file redirection.

-geometry is synonymous with -resize and specifies the size of the output image. The offsets, if present, are ignored.

-gravity <type>

direction primitive gravitates to when annotating the image. Choices are: NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast.

The direction you choose specifies where to position the text or other graphic primitive when annotating the image. For example Center gravity forces the text to be centered within the image. By default, the image gravity is NorthWest. See -draw for more details about graphic primitives.

The -gravity option is also used in concert with the -geometry option and other options that take <geometry> as a parameter, such as the -crop option. See -geometry for details of how the -gravity option interacts with the <x> and <y> parameters of a geometry specification.

-implode <factor>
implode image pixels about the center. It is a real number.
-lat <radius>x<sigma>{+-}<offset>{%}
perform local adaptive thresholding Perform local adaptive thresholding using the specified radius, sigma, and offset. The offset is a distance in sample space from the mean, as an absolute integer ranging from 0 to the maximum sample value or as a percentage. For reasonable results, radius should be larger than sigma. Use a radius of 0 to have the method select a suitable radius.
-level <value>
adjust the level of image contrast Give three point values delineated with commas: black, mid, and white (e.g. 10,1.0,65000). The white and black points range from 0 to MaxRGB and mid ranges from 0 to 10.
-linewidth
the line width for subsequent draw operations
-map <filename>
-mask <filename>

Specify a clipping mask The image read from the file is used as a clipping mask. It must have the same dimensions as the image being masked.

If the mask image contains an opacity channel, the opacity of each pixel is used to define the mask. Otherwise, the intensity (gray level) of each pixel is used.

Use +mask to remove the clipping mask.

It is not necessary to use -clip to activate the mask; -clip is implied by -mask.

-matte
-mattecolor <color>
-median <radius>
apply a median filter to the image
-monochrome
transform the image to black and white
-negate
replace every pixel with its complementary color The red, green, and blue intensities of an image are negated. White becomes black, yellow becomes blue, etc. Use +negate to only negate the grayscale pixels of the image.
-noise <radius|type>

add or reduce noise in an 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 pixel 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 pixel window.

Use radius to specify the width of the neighborhood.

Use +noise followed by a noise type to add noise to an image. Choose from these noise types:

Uniform Gaussian Multiplicative Impulse Laplacian Poisson
-normalize
transform image to span the full range of color values This is a contrast enhancement technique.
-opaque <color>
change this color to the pen color within the image The color is specified using the format described in the "Color Names" section of X(1).
-paint <radius>
simulate an oil painting Each pixel is replaced by the most frequent color in a circular neighborhood whose width is specified with radius.
-raise <width>x<height>

lighten or darken image edges This will create a 3-D effect. See -geometry for details details about the geometry specification. Offsets are not used.

Use -raise to create a raised effect, otherwise use +raise.

-region <width>x<height>{+-}<x>{+-}<y>
apply options to a portion of the image The x and y offsets are treated in the same manner as in -crop.
-resize <width>x<height>{%}{@}{!}{<}{>}

resize an image This is an alias for the -geometry option and it behaves in the same manner. If the -filter option precedes the -resize option, the specified filter is used.

There are some exceptions:

When used as a composite option, -resize conveys the preferred size of the output image, while -geometry conveys the size and placement of the composite image within the main image.

When used as a montage option, -resize conveys the preferred size of the montage, while -geometry conveys information about the tiles.

-roll {+-}<x>{+-}<y>

roll an image vertically or horizontally See -geometry for details the geometry specification. The x and y offsets are not affected by the -gravity option.

A negative x offset rolls the image left-to-right. A negative y offset rolls the image top-to-bottom.

-rotate <degrees>{<}{>}

apply Paeth image rotation to the image Use > to rotate the image only if its width exceeds the height. < rotates the image only if its width is less than the height. For example, if you specify -rotate "-90>" and the image size is 480x640, the image is not rotated. However, if the image is 640x480, it is rotated by -90 degrees. If you use > or <, enclose it in quotation marks to prevent it from being misinterpreted as a file redirection.

Empty triangles left over from rotating the image are filled with the color defined as background (class backgroundColor). See X(1) for details.

-sample <geometry>
scale image with pixel sampling See -geometry for details about the geometry specification. -sample ignores the -filter selection if the -filter option is present. Offsets, if present in the geometry string, are ignored, and the -gravity option has no effect.
-sampling_factor <horizontal_factor>x<vertical_factor>
sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder. This option specifies the sampling factors to be used by the JPEG encoder for chroma downsampling. If this option is omitted, the JPEG library will use its own default values. When reading or writing the YUV format and when writing the M2V (MPEG-2) format, use -sampling_factor 2x1 to specify the 4:2:2 downsampling method.
-scale <geometry>
scale the image. See -geometry for details about the geometry specification. -scale uses a simpler, faster algorithm, and it ignores the -filter selection if the -filter option is present. Offsets, if present in the geometry string, are ignored, and the -gravity option has no effect.
-seed <value> pseudo-random number generator seed value
-segment <cluster threshold>x<smoothing threshold>

segment an image Segment an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique.

Specify cluster threshold as the number of pixels in each cluster must exceed the the cluster threshold to be considered valid. Smoothing threshold eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative. The default is 1.5. See "Image Segmentation", below, for details.

-shade <azimuth>x<elevation>
shade the image using a distant light source Specify azimuth and elevation as the position of the light source. Use +shade to return the shading results as a grayscale image.
-sharpen <radius>x<sigma>
sharpen the image Use a Gaussian operator of the given radius and standard deviation (sigma).
-shave <width>x<height>
shave pixels from the image edges Specify the width of the region to be removed from both sides of the image and the height of the regions to be removed from top and bottom.
-shear <x degrees>x<y degrees>

shear the image along the X or Y axis Use the specified positive or negative shear angle.

Shearing slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x degrees is measured relative to the Y axis, and similarly, for Y direction shears y degrees is measured relative to the X axis.

Empty triangles left over from shearing the image are filled with the color defined as background (class backgroundColor). See X(1) for details.

-solarize <factor>

negate all pixels above the threshold level Specify factor as the percent threshold of the intensity (0 - 99.9%).

This option produces a solarization effect seen when exposing a photographic film to light during the development process.

-spread <amount>
displace image pixels by a random amount Amount defines the size of the neighborhood around each pixel to choose a candidate pixel to swap.
-stroke <color>

color to use when stroking a graphic primitive The color is specified using the format described in the "Color Names" section of X(1).

See -draw for further details.

-strokewidth <value>
set the stroke width See -draw for further details.
-swirl <degrees>

swirl image pixels about the center Degrees defines the tightness of the swirl.

-texture <filename>
-threshold <value>

threshold the image Create a bi-level image such that any pixel intensity that is equal or exceeds the threshold is reassigned the maximum intensity otherwise the minimum intensity.

-tile <filename>
-tile <geometry>
layout of images [montage]
-transform

transform the image This option applies the transformation matrix from a previous -affine option.

mogrify(img, '-affine 2,2,-2,2,0,0 -transform bird.ppm');

-transparent <color>
-treedepth <value>

tree depth for the color reduction algorithm Normally, this integer value is zero or one. A zero or one tells display to choose an optimal tree depth for the color reduction algorithm

An optimal depth generally allows the best representation of the source image with the fastest computational speed and the least amount of memory. However, the default depth is inappropriate for some images. To assure the best representation, try values between 2 and 8 for this parameter. Refer to quantize for more details.

The -colors or -monochrome option is required for this option to take effect.

-trim
trim an image This option removes any edges that are exactly the same color as the corner pixels. Use -fuzz to make -trim remove edges that are nearly the same color as the corner pixels.
-type <type>
-unsharp <radius>x<sigma>
sharpen the image with an unsharp mask operator Use the given radius and standard deviation (sigma).
-wave <amplitude>x<wavelength>
alter an image along a sine wave Specify amplitude and wavelength of the wave.

Image Segmentation

Use -segment to segment an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique. The scale-space filter analyzes the histograms of the three color components of the image and identifies a set of classes. The extents of each class is used to coarsely segment the image with thresholding. The color associated with each class is determined by the mean color of all pixels within the extents of a particular class. Finally, any unclassified pixels are assigned to the closest class with the fuzzy c-means technique.

The fuzzy c-Means algorithm can be summarized as follows:

Build a histogram, one for each color component of the image.

For each histogram, successively apply the scale-space filter and build an interval tree of zero crossings in the second derivative at each scale. Analyze this scale-space "fingerprint" to determine which peaks or valleys in the histogram are most predominant.

The fingerprint defines intervals on the axis of the histogram. Each interval contains either a minima or a maxima in the original signal. If each color component lies within the maxima interval, that pixel is considered "classified" and is assigned an unique class number.

Any pixel that fails to be classified in the above thresholding pass is classified using the fuzzy c-Means technique. It is assigned to one of the classes discovered in the histogram analysis phase.

The fuzzy c-Means technique attempts to cluster a pixel by finding the local minima of the generalized within group sum of squared error objective function. A pixel is assigned to the closest class of which the fuzzy membership has a maximum value.

For additional information see: Young Won Lim, Sang Uk Lee, "On The Color Image Segmentation Algorithm Based on the Thresholding and the Fuzzy c-Means Techniques", Pattern Recognition, Volume 23, Number 9, pages 935-952, 1990.

Authors

Availability

The latest version of SIP can be found at

http://siptoolbox.sf.net

See Also


<< mkfilter SIP - Scilab Image Processing Toolbox normal >>