The same 'artifact' settings can also be defined using the -set "option: key " " value " option, which also allows the use of Format and Print Image Properties in the defined value. The option and key are case-independent they are converted to lowercase for use within the decoders while the value is case-dependent. See ImageMagick Defines for a list of recognized defines. For example:. Set attributes of the image registry by prefixing the value with registry:.

For example, to set a temporary path to put work files, use:. The default is no delay between each showing of the image sequence.

The default ticks-per-second is However, if the image delay is 40 or 50, the delay it is changed to Negative indexes are relative to the end of the sequence, for example, -1 represents the last image of the sequence. Separate indexes with a comma e. Use -delete to delete the entire image sequence. You can also delete images from the persistent registry, e. Set the horizontal and vertical resolution of an image for rendering to devices.

This option specifies the image resolution to store while encoding a raster image or the canvas resolution while rendering reading vector formats such as Postscript, PDF, WMF, and SVG into a raster image. Image resolution provides the unit of measure to apply when rendering to an output device or raster image.

The default unit of measure is in dots per inch DPI. The -units option may be used to select dots per centimeter instead. The default resolution is 72 dots per inch, which is equivalent to one point per pixel Macintosh and Postscript standard. Computer screens are normally 72 or 96 dots per inch, while printers typically support , , , or dots per inch.

To determine the resolution of your display, use a ruler to measure the width of your screen in inches, and divide by the number of horizontal pixels on a x display. If the file format supports it, this option may be used to update the stored image resolution. Note that Photoshop stores and obtains image resolution from a proprietary embedded profile. If this profile is not stripped from the image, then Photoshop will continue to treat the image using its former resolution, ignoring the image resolution specified in the standard file header.

The -density option sets an attribute and does not alter the underlying raster image. It may be used to adjust the rendered size for desktop publishing purposes by adjusting the scale applied to the pixels. To resize the image so that it is the same size at a different resolution, use the -resample option. Color depth is the number of bits per channel for each pixel. Use this option to specify the depth of raw images formats whose depth is unknown such as GRAY, RGB, or CMYK, or to change the depth of any image after it has been read.

Use -set option:deskew:auto-crop true false to auto crop the image. Render text right-to-left or left-to-right. Requires the RAQM delegate library and complex text layout. With this option, the 'overlay' image, and optionally the 'mask' image, is used as a displacement map, which is used to displace the lookup of what part of the 'background' image is seen at each point of the overlaid area.

Much like the displacement map is a 'lens' that redirects light shining through it so as to present a distorted view the original 'background' image behind it. Any perfect grey areas of the displacement map produce a zero displacement of the image.

Black areas produce the given maximum negative displacement of the lookup point, while white produce a maximum positive displacement of the lookup. Note that it is the lookup of the 'background' that is displaced, not a displacement of the image itself. Understanding this is a very important in understanding how displacement maps work. The given arguments define the maximum amount of displacement in pixels that a particular map can produce.

If the displacement scale is large enough it is also possible to lookup parts of the 'background' image that lie well outside the bounds of the displacement map itself.

That is you could very easily copy a section of the original image from outside the overlay area into the overlay area. Using '! these flags were added as of IM v6.

Normally a single grayscale displacement map is provided, which with the given scaling values will determine a single direction vector in which displacements can occur positively or negatively. However, if you also specify a third image which is normally used as a mask , the composite image is used for horizontal X displacement, while the mask image is used for vertical Y displacement. This allows you to define completely different displacement values for the X and Y directions, and allowing you to lookup any point within the scale bounds.

In other words each pixel can lookup any other nearby pixel, producing complex 2 dimensional displacements, rather than a simple 1 dimensional vector displacements. Alternatively rather than supplying two separate images, as of IM v6. As of IM v6. However areas outside the overlaid areas will not be affected.

This option is used with convert for obtaining image or font from this X server. See X 1. Define the GIF disposal image setting for images that are being created or read in. The layer disposal method defines the way each the displayed image is to be modified after the current 'frame' of an animation has finished being displayed after its 'delay' period , but before the next frame on an animation is to be overlaid onto the display.

You can also use the numbers given above, which is what the GIF format uses internally to represent the above settings. Use -set ' dispose ' method to set the image disposal method for images already in memory. The opacity of the composite image is multiplied by the given percent, then it is composited 'over' the main image. If both percentages are given, each image are dissolved to the percentages given.

Distort an image, using the given method and its required arguments. The arguments is a single string containing a list of floating point numbers separated by commas or spaces. The number of and meaning of the floating point values depends on the distortion method being used. Many of the above distortion methods such as ' Affine ', ' Perspective ', and ' Shepards ' use a list control points defining how these points in the given image should be distorted in the destination image.

Each set of four floating point values represent a source image coordinate, followed immediately by the destination image coordinate. This produces a list of values such as For example, to warp an image using ' perspective ' distortion, needs a list of at least 4 sets of coordinates, or 16 numbers.

Here is the perspective distortion of the built-in "rose:" image. Note how spaces were used to group the 4 sets of coordinate pairs, to make it easier to read and understand. If more that the required number of coordinate pairs are given for a distortion, the distortion method is 'least squares' fitted to produce the best result for all the coordinate pairs given. If less than the ideal number of points are given, the distort will generally fall back to a simpler form of distortion that can handles the smaller number of coordinates usually a linear ' Affine ' distortion.

By using more coordinates you can make use of image registration tool to find matching coordinate pairs in overlapping images, so as to improve the 'fit' of the distortion.

Of course a bad coordinate pair can also make the 'fit' worse. Caution is always advised. Colors are acquired from the source image according to a cylindrical resampling -filter , using a special technique known as EWA resampling. This produces very high quality results, especially when images become smaller minified in the output, which is very common when using ' perspective ' distortion. For example here we view a infinitely tiled 'plane' all the way to the horizon.

Note that a infinitely tiled perspective images involving the horizon can be very slow, because of the number of pixels that are compressed to generate each individual pixel close to the 'horizon'. You can turn off EWA resampling, by specifying the special -filter setting of ' point ' recommended if you plan to use super-sampling instead. If an image generates invalid pixels , such as the 'sky' in the last example, -distort will use the current -mattecolor setting for these pixels.

If you do not what these pixels to be visible, set the color to match the rest of the ground. The output image size will by default be the same as the input image. This means that if the part of the distorted image falls outside the viewed area of the 'distorted space', those parts is clipped and lost. Setting -verbose setting, will cause -distort to attempt to output the internal coefficients, and the -fx equivalent to the distortion, for expert study, and debugging purposes.

This many not be available for all distorts. This can be used either for 'super-sampling' the image for a higher quality result, or for panning and zooming around the image with appropriate viewport changes, or post-distort cropping and resizing. Note this table uses a squared radius lookup value. This is typically only used for debugging EWA resampling.

Apply a Riemersma or Floyd-Steinberg error diffusion dither to images when general color reduction is applied via an option, or automagically when saving to specific formats.

This enabled by default. Dithering places two or more colors in neighboring pixels so that to the eye a closer approximation of the images original color is reproduced.

This reduces the number of colors needed to reproduce the image but at the cost of a lower level pattern of colors. Error diffusion dithers can use any set of colors generated or user defined to an image. This will also render PostScript without text or graphic aliasing. Disabling dithering often but not always leads to faster process, a smaller number of colors, but more cartoon like image coloring.

Generally resulting in 'color banding' effects in areas with color gradients. The color reduction operators -colors , -monochrome , -remap , and -posterize , apply dithering to images using the reduced color set they created.

These operators are also used as part of automatic color reduction when saving images to formats with limited color support, such as GIF: , XBM: , and others, so dithering may also be used in these cases. Alternatively you can use -random-threshold to generate purely random dither. Or use -ordered-dither to apply threshold mapped dither patterns, using uniform color maps, rather than specific color maps. Use this option to annotate or decorate an image with one or more graphic primitives.

The primitives include shapes, text, transformations, and pixel operations. The text gravity primitive only affects the placement of text and does not interact with the other primitives. It is equivalent to using the -gravity command-line option, except that it is limited in scope to the -draw option in which it appears. The shape primitives are drawn in the color specified by the preceding -fill setting. For unfilled shapes, use -fill none.

You can optionally control the stroke the "outline" of a shape with the -stroke and -strokewidth settings. A point primitive is specified by a single point in the pixel plane, that is, by an ordered pair of integer coordinates, x , y. As it involves only a single pixel, a point primitive is not affected by -stroke or -strokewidth.

A rectangle primitive is specified by the pair of points at the upper left and lower right corners. A roundRectangle primitive takes the same corner points as a rectangle followed by the width and height of the rounded corners to be removed. The circle primitive makes a disk filled or circle unfilled. Give the center and any point on the perimeter boundary. Note, by using a translation, you can remove the need to calculate the circles edge coordinate, but can just give the radius directly:.

The arc primitive is used to inscribe an elliptical segment in to a given rectangle. An arc requires the two corners used for rectangle see above followed by the start and end angles of the arc of the segment e. The start and end points produced are then joined with a line segment and the resulting segment of an ellipse is filled. Use ellipse to draw a partial or whole ellipse.

Give the center point, the horizontal and vertical "radii" the semi-axes of the ellipse and start and end angles in degrees e. The polyline and polygon primitives require three or more points to define their perimeters. A polyline is simply a polygon in which the final point is not stroked to the start point.

When unfilled, this is a polygonal line. If the -stroke setting is none the default , then a polyline is identical to a polygon. The Bezier primitive creates a spline curve and requires three or points to define its shape. The first and last points are the knots and these points are attained by the curve, while any intermediate coordinates are control points. If two control points are specified, the line between each end knot and its sequentially respective control point determines the tangent direction of the curve at that end.

If one control point is specified, the lines from the end knots to the one control point determines the tangent directions of the curve at each end. If more than two control points are specified, then the additional control points act in combination to determine the intermediate shape of the curve. In order to draw complex curves, it is highly recommended either to use the path primitive or to draw multiple four-point bezier segments with the start and end knots of each successive segment repeated.

A path represents an outline of an object, defined in terms of moveto set a new current point , lineto draw a straight line , curveto draw a Bezier curve , arc elliptical or circular arc and closepath close the current shape by drawing a line to the last moveto elements.

Compound paths i. See Paths. Use image to composite an image with another image. Follow the image keyword with the composite operator, image location, image size, and filename:. You can use 0,0 for the image size, which means to use the actual dimensions found in the image header. Otherwise, it is scaled to the given dimensions. See Alpha Compositing for a detailed discussion of alpha composition methods that are available.

The "special augmented compose operators" such as "dissolve" that require arguments cannot be used at present with the -draw image option. Use text to annotate an image with text.

Follow the text coordinates with a string. If the string has embedded spaces, enclose it in single or double quotes. For example, the following annotates the image with Works like magick! for an image titled bird. See the -annotate option for another convenient way to annotate an image with text. The rotate primitive rotates subsequent shape primitives and text primitives about the origin of the main image:. The skewX and skewY primitives skew them with respect to the origin 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 the color primitive to change the color of a pixel to the fill color see -fill.

Follow the pixel coordinate with a method:. 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. Use matte to the change the pixel matte value to transparent. Follow the pixel coordinate with a method see the color primitive for a description of methods.

The point method changes the matte value of the target pixel. The replace method changes the matte value of any pixel that matches the color of the target pixel. Floodfill changes the matte value of any pixel that matches the color of the target pixel and is a neighbor, whereas filltoborder changes the matte value of any neighbor pixel that is not the border color -bordercolor.

Finally reset changes the matte value of all pixels. You can set the primitive color, font, and font bounding box color with -fill , -font , and -box respectively. Options are processed in command line order so be sure to use these options before the -draw option.

Drawing primitives conform to the Magick Vector Graphics format. Note, drawing requires an alpha channel. If none is available, an all opaque alpha channel is implicitedly created. Specify the count and the image to duplicate by its index in the sequence. Encipher pixels for later deciphering by -decipher. Specify endianness MSB or LSB of the image. To perform histogram equalization on all channels in concert, transform the image into some other color space, such as HSL, OHTA, YIQ or YUV, then equalize the appropriate intensity-like channel, then convert back to RGB.

For example using HSL, we have For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal components transformation that puts most of the information in the first channel. Here we have Alter channel pixels by evaluating an arithmetic, relational, or logical expression. See the -function operator for some multi-parameter functions.

See the -fx operator if more elaborate calculations are needed. The behaviors of each operator are summarized in the following list. For brevity, the numerical value of a "pixel" referred to below is the value of the corresponding channel of that pixel, while a "normalized pixel" is that number divided by the maximum installation-dependent value QuantumRange. If normalized pixels are used, they are restored, following the other calculations, to the full range by multiplying by QuantumRange.

The specified functions are applied only to each previously set -channel in the image. If necessary, the results of the calculations are truncated clipped to fit in the interval [0, QuantumRange ]. To print a complete list of -evaluate operators, use -list evaluate. AddModulus has been added as of ImageMagick 6. It is therefore equivalent to Add unless the resulting pixel value is outside the interval [0, QuantumRange ]. Exp or Exponential has been added as of ImageMagick 6. The value used with Exp should be negative so as to produce a decaying exponential function.

Non-negative values will always produce results larger unity and thus outside the interval [0, QuantumRange ]. The formula is expressed below. If the input image is squared, for example, using -function polynomial "2 0 0" , then a decaying Gaussian function will be the result.

Log has been added as of ImageMagick 6. This a scaled log function. The value used with Log provides a scaling factor that adjusts the curvature in the graph of the log function.

The formula applied to a normalized value u is below. Pow has been added as of ImageMagick 6. Note that Pow is related to the -gamma operator. For example, -gamma 2 is equivalent to -evaluate pow 0. The value used with -gamma is simply the reciprocal of the value used with Pow.

Cosine and Sine was added as of IM v6. The synonyms Cos and Sin may also be used. The value scaling of the period of the function its frequency , and thus determines the number of 'waves' that will be generated over the input color range.

For example, if the value is 1, the effective period is simply the QuantumRange ; but if the value is 2, then the effective period is the half the QuantumRange. See also the -function operator, which is a multi-value version of evaluate.

Alter channel pixels by evaluating an arithmetic, relational, or logical expression over a sequence of images. Ensure all the images in the sequence are in the same colorspace, otherwise you may get unexpected results, e. add -colorspace sRGB to your command-line. To print a complete list of -evaluate-sequence operators, use -list evaluate. No further options are processed after this option. Useful in a script to force the magick command to exit without actually closing the pipeline that it is processing options from.

You can also use the option as a final option on the magick command line instead of an implicit output image, to completely prevent any image write. Note, even the NULL: coder requires at least one image, for it to 'not write'!

This option does not require any images at all. If the image is enlarged, unfilled areas are set to the background color. To position the image, use offsets in the geometry specification or precede with a -gravity setting.

To specify how to compose the image with the background, use -compose. The following command reduces or expands a JPEG image to fit on an x display. If the aspect ratio of the input image isn't exactly , then the image is centered on an x black canvas:.

The command can also be used with a ratio. If the image is not already at that ratio, it will be cropped to fit it. The -gravity setting has the expected effects. The following command crops a JPEG image so that it has a ratio:. This option is most useful for extracting a subregion of a very large raw image.

Note that these two commands are equivalent:. This setting suggests a font family that ImageMagick should try to use for rendering text. If the family can be found it is used; if not, a default font e. Note, the family can be a CSS-style font list. For other settings that affect fonts, see the options -font , -pointsize , -stretch , -style , and -weight. Display co-occurrence matrix texture measure features for each channel in the image in each of four directions horizontal, vertical, left and right diagonals for the specified distance.

This option is new as of ImageMagick 6. It transforms an image from the normal spatial domain to the frequency domain. In the frequency domain, an image is represented as a superposition of complex sinusoidal waves of varying amplitudes. The image x and y coordinates are the possible frequencies along the x and y directions, respectively, and the pixel intensity values are complex numbers that correspond to the sinusoidal wave amplitudes. See for example, Fourier Transform , Discrete Fourier Transform and Fast Fourier Transform.

A single image name is provided as output for this option. However, the output result will have two components. It is either a two-frame image or two separate images, depending upon whether the image format specified supports multi-frame images. The reason that we get a dual output result is because the frequency domain represents an image using complex numbers, which cannot be visualized directly.

Therefore, the complex values are automagically separated into a two-component image representation. The first component is the magnitude of the complex number and the second is the phase of the complex number. See for example, Complex Numbers. The magnitude and phase component images must be specified using image formats that do not limit the color or compress the image.

Thus, MIFF, TIF, PFM, EXR and PNG are the recommended image formats to use. All of these formats, except PNG support multi-frame images. So for example,. The input image can be any size, but if not square and even-dimensioned, it is padded automagically to the larger of the width or height of the input image and to an even number of pixels.

The resulting output magnitude and phase images is square at this size. The kind of padding relies on the -virtual-pixel setting. Both output components will have dynamic ranges that fit within [0, QuantumRange ], so that HDRI need not be enabled.

The first few releases had non-HDRI scaled but HDRI not scaled. The magnitude image is not scaled and thus generally will contain very small values. As such, the image normally will appear totally black. In order to view any detail, the magnitude image typically is enhanced with a log function into what is usually called the spectrum.

A log function is used to enhance the darker values more in comparison to the lighter values. This can be done, for example, as follows:. where either -contrast-stretch 0 or -auto-level is used to scale the image to full dynamic range, first.

The argument to the -evaluate log typically is specified between and 10,, depending upon the amount of detail that one wants to bring out in the spectrum. Larger values produce more visible detail. Too much detail, however, may hide the important features. The FFTW delegate library is required to use -fft. However, as the real and imaginary components can contain negative values, this requires that IM be configured with HDRI enabled.

In this case, you must use either MIFF, TIF, PFM or MPC formats for the real and imaginary component results, since they are formats that preserve both negative and fractional values without clipping them or truncating the fractional part. For more about HDRI go the ImageMagick Usage pages, Fred's Fourier Processing With ImageMagick page or this Wikipedia entry. By default the FFT is normalized and the IFT is not.

This option accepts a color name, a hex color, or a numerical RGB, RGBA, HSL, HSLA, CMYK, or CMYKA specification. See Color Names for a description of how to properly specify the color argument. Enclose the color specification in quotation marks to prevent the " " or the parentheses from being interpreted by your shell.

Use this type of filter when resizing or distorting an image. Use this option to affect the resizing operation of an image during operations such as -resize and -distort. For example you can use a simple resize filter such as:. The Bessel and Sinc filter is also provided as well as a faster SincFast equivalent form. However these filters are generally useless on their own as they are infinite filters that are being clipped to the filters support size.

Their direct use is not recommended except via expert settings see below. Instead these special filter functions are typically windowed by a windowing function that the -filter setting defines. That is using these functions will define a 'Windowed' filter, appropriate to the operator involved. Windowed filters include:. Also one special self-windowing filter is also provided Lagrange , which will automagically re-adjust its function depending on the current 'support' or 'lobes' expert settings see below.

If you do not select a filter with this option, the filter defaults to Mitchell for a colormapped image, an image with a matte channel, or if the image is enlarged. Otherwise the filter default to Lanczos. You can modify how the filter behaves as it scales your image through the use of these expert settings see also -define and -set To extract the data for a raw windowing function, combine it with a ' Box ' filter. For example the ' Welch parabolic windowing function.

Note that the use of expert options is provided for image processing experts who have studied and understand how resize filters work. Without this knowledge, and an understanding of the definition of the actual filters involved, using expert settings are more likely to be detrimental to your image resizing. This is a simple alias for the -layers method "flatten". Flood fill starts from the given 'seed point' which is not gravity affected.

Any color that matches within -fuzz color distance of the given color argument, connected to that 'seed point' will be replaced with the current -fill color. Note that if the pixel at the 'seed point' does not itself match the given color according to -fuzz , then no action will be taken. This operator works more like the -opaque option, than a more general flood fill that reads the matching color directly at the 'seed point'.

For this form of flood fill, look at -draw and its 'color floodfill' drawing method. Set the font to use when annotating images with text, or creating labels. To print a complete list of fonts, use the -list font option for versions prior to 6. In addition to the fonts specified by the above pre-defined list, you can also specify a font from a specific source. For example Arial.

ttf is a TrueType font file, ps:helvetica is PostScript font, and x:fixed is X11 font. For other settings that affect fonts, see the options -family , -stretch , -style , and -weight. To specify an explicit font filename or collection, specify the font path preceded with a , e.

You can specify the font face index for font collections, e. When used with the mogrify utility, this option converts any image to the image format you specify. For a list of image format types supported by ImageMagick, use -list format.

By default the file is written to its original name. However, if the filename extension matches a supported format, the extension is replaced with the image format type specified with -format. For example, if you specify tiff as the format type and the input image filename is image. gif , the output image filename becomes image. See Format and Print Image Properties for an explanation on how to specify the argument to this option. The color of the border is specified with the -mattecolor command line option.

The size portion of the geometry argument indicates the amount of extra width and height that is added to the dimensions of the image. If no offsets are given in the geometry argument, then the border added is a solid color.

Offsets x and y , if present, specify that the width and height of the border is partitioned to form an outer bevel of thickness x pixels and an inner bevel of thickness y pixels.

Negative offsets make no sense as frame arguments. The -frame option is affected by the current -compose setting and assumes that this is using the default ' Over ' composition method. It generates an image of the appropriate size with the current -bordercolor setting, and then draws the frame of four distinct colors close to the current -mattecolor.

The original image is then overlaid onto center of this image. This operator performs calculations based on the given arguments to modify each of the color values for each previously set -channel in the image.

See -evaluate for details concerning how the results of the calculations are handled. This is can be considered a multi-argument version of the -evaluate operator. Added in ImageMagick 6. Here, parameters is a comma-separated list of numerical values. The number of values varies depending on which function is selected. Choose the function from:. To print a complete list of -function operators, use -list function.

Descriptions follow. The Polynomial function takes an arbitrary number of parameters, these being the coefficients of a polynomial, in decreasing order of degree. That is, entering. The Polynomial function can be used in place of Set the constant polynomial and Add , Divide , Multiply , and Subtract some linear polynomials of the -evaluate operator.

The -level operator also affects channels linearly. Some correspondences follow. The Polynomial function gives great versatility, since polynomials can be used to fit any continuous curve to any degree of accuracy desired. The Sinusoid function can be used to vary the channel values sinusoidally by setting frequency, phase shift, amplitude, and a bias.

These values are given as one to four parameters, as follows,. where phase is in degrees. The domain [0,1] of the function corresponds to 0 through freq × degrees. The result is that if a pixel's normalized channel value is originally u , its resulting normalized value is given by.

For example, the following generates a curve that starts and ends at 0. Perform final value replacement. If a variable is modified in a loop in such a way that its value when exiting the loop can be determined using only its initial value and the number of loop iterations, replace uses of the final value by such a computation, provided it is sufficiently cheap.

This reduces data dependencies and may allow further simplifications. Perform induction variable optimizations strength reduction, induction variable merging and induction variable elimination on trees. Parallelize loops, i. This is only possible for loops whose iterations are independent and can be arbitrarily reordered. The optimization is only profitable on multiprocessor machines, for loops that are CPU-intensive, rather than constrained e. by memory bandwidth.

This option implies -pthread , and thus is only supported on targets that have support for -pthread. Perform function-local points-to analysis on trees. This flag is enabled by default at -O1 and higher, except for -Og. Perform scalar replacement of aggregates. This pass replaces structure references with scalars to prevent committing structures to memory too early.

Perform merging of narrow stores to consecutive memory addresses. This pass merges contiguous stores of immediate values narrower than a word into fewer wider stores to reduce the number of instructions.

This is enabled by default at -O2 and higher as well as -Os. This results in non-GIMPLE code, but gives the expanders much more complex trees to work on resulting in better RTL generation. This is enabled by default at -O1 and higher. Perform straight-line strength reduction on trees. This recognizes related expressions involving multiplications and replaces them by less expensive calculations when possible.

Perform vectorization on trees. This flag enables -ftree-loop-vectorize and -ftree-slp-vectorize if not explicitly specified. Perform loop vectorization on trees. This flag is enabled by default at -O2 and by -ftree-vectorize , -fprofile-use , and -fauto-profile. Perform basic block vectorization on trees. Initialize automatic variables with either a pattern or with zeroes to increase the security and predictability of a program by preventing uninitialized memory disclosure and use.

With this option, GCC will also initialize any padding of automatic variables that have structure or union types to zeroes.

However, the current implementation cannot initialize automatic variables that are declared between the controlling expression and the first case of a switch statement. Using -Wtrivial-auto-var-init to report all such cases. You can control this behavior for a specific variable by using the variable attribute uninitialized see Variable Attributes.

Alter the cost model used for vectorization. Alter the cost model used for vectorization of loops marked with the OpenMP simd directive. All values of model have the same meaning as described in -fvect-cost-model and by default a cost model defined with -fvect-cost-model is used. Perform Value Range Propagation on trees. This is similar to the constant propagation pass, but instead of values, ranges of values are propagated.

This allows the optimizers to remove unnecessary range checks like array bound checks and null pointer checks. This is enabled by default at -O2 and higher. Null pointer check elimination is only done if -fdelete-null-pointer-checks is enabled. Split paths leading to loop backedges. This can improve dead code elimination and common subexpression elimination. This is enabled by default at -O3 and above. Enables expression of values of induction variables in later iterations of the unrolled loop using the value in the first iteration.

This breaks long dependency chains, thus improving efficiency of the scheduling passes. A combination of -fweb and CSE is often sufficient to obtain the same effect. However, that is not reliable in cases where the loop body is more complicated than a single basic block.

It also does not work at all on some architectures due to restrictions in the CSE pass. With this option, the compiler creates multiple copies of some local variables when unrolling a loop, which can result in superior code. Inline parts of functions. Perform predictive commoning optimization, i. This option is enabled at level -O3. If supported by the target machine, generate instructions to prefetch memory to improve the performance of loops that access large arrays. This option may generate better or worse code; results are highly dependent on the structure of loops within the source code.

Do not substitute constants for known return value of formatted output functions such as sprintf , snprintf , vsprintf , and vsnprintf but not printf of fprintf. This transformation allows GCC to optimize or even eliminate branches based on the known return value of these functions called with arguments that are either constant, or whose values are known to be in a range that makes determining the exact return value possible.

For example, when -fprintf-return-value is in effect, both the branch and the body of the if statement but not the call to snprint can be optimized away when i is a bit or smaller integer because the return value is guaranteed to be at most 8. The -fprintf-return-value option relies on other optimizations and yields best results with -O2 and above.

It works in tandem with the -Wformat-overflow and -Wformat-truncation options. The -fprintf-return-value option is enabled by default. Disable any machine-specific peephole optimizations. The difference between -fno-peephole and -fno-peephole2 is in how they are implemented in the compiler; some targets use one, some use the other, a few use both. GCC uses heuristics to guess branch probabilities if they are not provided by profiling feedback -fprofile-arcs.

These heuristics are based on the control flow graph. The default is -fguess-branch-probability at levels -O , -O2 , -O3 , -Os. Reorder basic blocks in the compiled function in order to reduce number of taken branches and improve code locality.

Use the specified algorithm for basic block reordering. In addition to reordering basic blocks in the compiled function, in order to reduce number of taken branches, partitions hot and cold basic blocks into separate sections of the assembly and. o files, to improve paging and cache locality performance. When -fsplit-stack is used this option is not enabled by default to avoid linker errors , but may be enabled explicitly if using a working linker.

Reorder functions in the object file in order to improve code locality. This is implemented by using special subsections. hot for most frequently executed functions and. unlikely for unlikely executed functions. Reordering is done by the linker so object file format must support named sections and linker must place them in a reasonable way.

Allow the compiler to assume the strictest aliasing rules applicable to the language being compiled. In particular, an object of one type is assumed never to reside at the same address as an object of a different type, unless the types are almost the same.

A character type may alias any other type. Even with -fstrict-aliasing , type-punning is allowed, provided the memory is accessed through the union type. So, the code above works as expected. See Structures unions enumerations and bit-fields implementation. However, this code might not:.

Similarly, access by taking the address, casting the resulting pointer and dereferencing the result has undefined behavior, even if the cast uses a union type, e. The -fstrict-aliasing option is enabled at levels -O2 , -O3 , -Os. Controls whether rules of -fstrict-aliasing are applied across function boundaries.

Note that if multiple functions gets inlined into a single function the memory accesses are no longer considered to be crossing a function boundary. The -fipa-strict-aliasing option is enabled by default and is effective only in combination with -fstrict-aliasing. Align the start of functions to the next power-of-two greater than or equal to n , skipping up to m -1 bytes.

This ensures that at least the first m bytes of the function can be fetched by the CPU without crossing an n -byte alignment boundary. If m2 is not specified, it defaults to n2.

Some assemblers only support this flag when n is a power of two; in that case, it is rounded up. If n is not specified or is zero, use a machine-dependent default.

The maximum allowed n option value is If this option is enabled, the compiler tries to avoid unnecessarily overaligning functions. It attempts to instruct the assembler to align by the amount specified by -falign-functions , but not to skip more bytes than the size of the function. Parameters of this option are analogous to the -falign-functions option. If -falign-loops or -falign-jumps are applicable and are greater than this value, then their values are used instead.

Align loops to a power-of-two boundary. If the loops are executed many times, this makes up for any execution of the dummy padding instructions. Align branch targets to a power-of-two boundary, for branch targets where the targets can only be reached by jumping.

In this case, no dummy operations need be executed. Allow the compiler to perform optimizations that may introduce new data races on stores, without proving that the variable cannot be concurrently accessed by other threads.

Does not affect optimization of local data. It is safe to use this option if it is known that global data will not be accessed by multiple threads. Examples of optimizations enabled by -fallow-store-data-races include hoisting or if-conversions that may cause a value that was already in memory to be re-written with that same value. Such re-writing is safe in a single threaded context but may be unsafe in a multi-threaded context.

Note that on some processors, if-conversions may be required in order to enable vectorization. This option is left for compatibility reasons. Do not reorder top-level functions, variables, and asm statements. Output them in the same order that they appear in the input file. When this option is used, unreferenced static variables are not removed. This option is intended to support existing code that relies on a particular ordering.

For new code, it is better to use attributes when possible. Additionally -fno-toplevel-reorder implies -fno-section-anchors. This also affects any such calls implicitly generated by the compiler. Constructs webs as commonly used for register allocation purposes and assign each web individual pseudo register.

This allows the register allocation pass to operate on pseudos directly, but also strengthens several other optimization passes, such as CSE, loop optimizer and trivial dead code remover. Assume that the current compilation unit represents the whole program being compiled. This option should not be used in combination with -flto. Instead relying on a linker plugin should provide safer and more precise information. This option runs the standard link-time optimizer.

When the object files are linked together, all the function bodies are read from these ELF sections and instantiated as if they had been part of the same translation unit. To use the link-time optimizer, -flto and optimization options should be specified at compile time and during the final link. It is recommended that you compile all the files participating in the same link with the same options and also specify those options at link time. For example:. The first two invocations to GCC save a bytecode representation of GIMPLE into special ELF sections inside foo.

o and bar. The final invocation reads the GIMPLE bytecode from foo. o , merges the two files into a single internal image, and compiles the result as usual. Since both foo. o are merged into a single image, this causes all the interprocedural analyses and optimizations in GCC to work across the two files as if they were a single one. This means, for example, that the inliner is able to inline functions in bar. o into functions in foo.

o and vice-versa. The above generates bytecode for foo. c and bar. c , merges them together into a single GIMPLE representation and optimizes them as usual to produce myprog.

The important thing to keep in mind is that to enable link-time optimizations you need to use the GCC driver to perform the link step. GCC automatically performs link-time optimization if any of the objects involved were compiled with the -flto command-line option.

You can always override the automatic decision to do link-time optimization by passing -fno-lto to the link command. To make whole program optimization effective, it is necessary to make certain whole program assumptions. The compiler needs to know what functions and variables can be accessed by libraries and runtime outside of the link-time optimized unit. When supported by the linker, the linker plugin see -fuse-linker-plugin passes information to the compiler about used and externally visible symbols.

When the linker plugin is not available, -fwhole-program should be used to allow the compiler to make these assumptions, which leads to more aggressive optimization decisions. When a file is compiled with -flto without -fuse-linker-plugin , the generated object file is larger than a regular object file because it contains GIMPLE bytecodes and the usual final code see -ffat-lto-objects.

This means that object files with LTO information can be linked as normal object files; if -fno-lto is passed to the linker, no interprocedural optimizations are applied. Note that when -fno-fat-lto-objects is enabled the compile stage is faster but you cannot perform a regular, non-LTO link on them.

When producing the final binary, GCC only applies link-time optimizations to those files that contain bytecode. Therefore, you can mix and match object files and libraries with GIMPLE bytecodes and final object code.

GCC automatically selects which files to optimize in LTO mode and which files to link without further processing. Generally, options specified at link time override those specified at compile time, although in some cases GCC attempts to infer link-time options from the settings used to compile the input files.

If you do not specify an optimization level option -O at link time, then GCC uses the highest optimization level used when compiling the object files. Note that it is generally ineffective to specify an optimization level option only at link time and not at compile time, for two reasons. First, compiling without optimization suppresses compiler passes that gather information needed for effective optimization at link time. Second, some early optimization passes can be performed only at compile time and not at link time.

There are some code generation flags preserved by GCC when generating bytecodes, as they need to be used during the final link. Currently, the following options and their settings are taken from the first object file that explicitly specifies them: -fcommon , -fexceptions , -fnon-call-exceptions , -fgnu-tm and all the -m target flags.

The following options -fPIC , -fpic , -fpie and -fPIE are combined based on the following scheme:. Certain ABI-changing flags are required to match in all compilation units, and trying to override this at link time with a conflicting value is ignored. This includes options such as -freg-struct-return and -fpcc-struct-return. Other options such as -ffp-contract , -fno-strict-overflow , -fwrapv , -fno-trapv or -fno-strict-aliasing are passed through to the link stage and merged conservatively for conflicting translation units.

You can override them at link time. Diagnostic options such as -Wstringop-overflow are passed through to the link stage and their setting matches that of the compile-step at function granularity. Note that this matters only for diagnostics emitted during optimization. Note that code transforms such as inlining can lead to warnings being enabled or disabled for regions if code not consistent with the setting at compile time. When you need to pass options to the assembler via -Wa or -Xassembler make sure to either compile such translation units with -fno-lto or consistently use the same assembler options on all translation units.

You can alternatively also specify assembler options at LTO link time. To enable debug info generation you need to supply -g at compile time.

If any of the input files at link time were built with debug info generation enabled the link will enable debug info generation as well. Any elaborate debug info settings like the dwarf level -gdwarf-5 need to be explicitly repeated at the linker command line and mixing different settings in different translation units is discouraged.

If LTO encounters objects with C linkage declared with incompatible types in separate translation units to be linked together undefined behavior according to ISO C99 6. The behavior is still undefined at run time.

Similar diagnostics may be raised for other languages. Another feature of LTO is that it is possible to apply interprocedural optimizations on files written in different languages:. In general, when mixing languages in LTO mode, you should use the same link command options as when mixing languages in a regular non-LTO compilation. If object files containing GIMPLE bytecode are stored in a library archive, say libfoo.

a , it is possible to extract and use them in an LTO link if you are using a linker with plugin support. To create static libraries suitable for LTO, use gcc-ar and gcc-ranlib instead of ar and ranlib ; to show the symbols of object files with GIMPLE bytecode, use gcc-nm.

Those commands require that ar , ranlib and nm have been compiled with plugin support. At link time, use the flag -fuse-linker-plugin to ensure that the library participates in the LTO optimization process:.

With the linker plugin enabled, the linker extracts the needed GIMPLE files from libfoo. a and passes them on to the running GCC to make them part of the aggregated GIMPLE image to be optimized. a are extracted and linked as usual, but they do not participate in the LTO optimization process.

In order to make a static library suitable for both LTO optimization and usual linkage, compile its object files with -flto -ffat-lto-objects. Link-time optimizations do not require the presence of the whole program to operate.

If the program does not require any symbols to be exported, it is possible to combine -flto and -fwhole-program to allow the interprocedural optimizers to use more aggressive assumptions which may lead to improved optimization opportunities.

Use of -fwhole-program is not needed when linker plugin is active see -fuse-linker-plugin. The current implementation of LTO makes no attempt to generate bytecode that is portable between different types of hosts. The bytecode files are versioned and there is a strict version check, so bytecode files generated in one version of GCC do not work with an older or newer version of GCC. Link-time optimization does not work well with generation of debugging information on systems other than those using a combination of ELF and DWARF.

If you specify the optional n , the optimization and code generation done at link time is executed in parallel using n parallel jobs by utilizing an installed make program. The environment variable MAKE may be used to override the program used. This is useful when the Makefile calling GCC is already executing in parallel. This option likely only works if MAKE is GNU make. Specify the partitioning algorithm used by the link-time optimizer. This option specifies the level of compression used for intermediate language written to LTO object files, and is only meaningful in conjunction with LTO mode -flto.

GCC currently supports two LTO compression algorithms. For zstd, valid values are 0 no compression to 19 maximum compression , while zlib supports values from 0 to 9. Values outside this range are clamped to either minimum or maximum of the supported values. If the option is not given, a default balanced compression setting is used.

Enables the use of a linker plugin during link-time optimization. This option relies on plugin support in the linker, which is available in gold or in GNU ld 2. This option enables the extraction of object files with GIMPLE bytecode out of library archives. This improves the quality of optimization by exposing more code to the link-time optimizer. This information specifies what symbols can be accessed externally by non-LTO object or during dynamic linking.

Resulting code quality improvements on binaries and shared libraries that use hidden visibility are similar to -fwhole-program. See -flto for a description of the effect of this flag and how to use it. This option is enabled by default when LTO support in GCC is enabled and GCC was configured for use with a linker supporting plugins GNU ld 2.

Fat LTO objects are object files that contain both the intermediate language and the object code. This makes them usable for both LTO linking and normal linking. This option is effective only when compiling with -flto and is ignored at link time.

It requires a linker with linker plugin support for basic functionality. Additionally, nm , ar and ranlib need to support linker plugins to allow a full-featured build environment capable of building static libraries etc. GCC provides the gcc-ar , gcc-nm , gcc-ranlib wrappers to pass the right options to these tools.

With non fat LTO makefiles need to be modified to use them. Note that modern binutils provide plugin auto-load mechanism. After register allocation and post-register allocation instruction splitting, identify arithmetic instructions that compute processor flags similar to a comparison operation based on that arithmetic. If possible, eliminate the explicit comparison operation.

This pass only applies to certain targets that cannot explicitly represent the comparison operation before register allocation is complete. After register allocation and post-register allocation instruction splitting, perform a copy-propagation pass to try to reduce scheduling dependencies and occasionally eliminate the copy.

Profiles collected using an instrumented binary for multi-threaded programs may be inconsistent due to missed counter updates. When this option is specified, GCC uses heuristics to correct or smooth out such inconsistencies. By default, GCC emits an error message when an inconsistent profile is detected. With -fprofile-use all portions of programs not executed during train run are optimized agressively for size rather than speed.

In some cases it is not practical to train all possible hot paths in the program. For example, program may contain functions specific for a given hardware and trianing may not cover all hardware configurations program is run on.

With -fprofile-partial-training profile feedback will be ignored for all functions not executed during the train run leading them to be optimized as if they were compiled without profile feedback. This leads to better performance when train run is not representative but also leads to significantly bigger code. Enable profile feedback-directed optimizations, and the following optimizations, many of which are generally profitable only with profile feedback available:. Before you can use this option, you must first generate profiling information.

See Instrumentation Options , for information about the -fprofile-generate option. By default, GCC emits an error message if the feedback profiles do not match the source code. Note this may result in poorly optimized code.

Additionally, by default, GCC also emits a warning message if the feedback profiles do not exist see -Wmissing-profile. If path is specified, GCC looks at the path to find the profile feedback data files.

See -fprofile-dir. Enable sampling-based feedback-directed optimizations, and the following optimizations, many of which are generally profitable only with profile feedback available:. path is the name of a file containing AutoFDO profile information. If omitted, it defaults to fbdata. afdo in the current directory. You must also supply the unstripped binary for your program to this tool.

The following options control compiler behavior regarding floating-point arithmetic. These options trade off between speed and correctness. All must be specifically enabled. Do not store floating-point variables in registers, and inhibit other options that might change whether a floating-point value is taken from a register or memory.

This option prevents undesirable excess precision on machines such as the where the floating registers of the keep more precision than a double is supposed to have.

Similarly for the x86 architecture. For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point. Use -ffloat-store for such programs, after modifying them to store all pertinent intermediate computations into variables. This option allows further control over excess precision on machines where floating-point operations occur in a format with more precision or range than the IEEE standard and interchange floating-point types.

It may, however, yield faster code for programs that do not require the guarantees of these specifications. Do not set errno after calling math functions that are executed with a single instruction, e.

A program that relies on IEEE exceptions for math error handling may want to use this flag for speed while maintaining IEEE arithmetic compatibility. On Darwin systems, the math library never sets errno. There is therefore no reason for the compiler to consider the possibility that it might, and -fno-math-errno is the default.

Allow optimizations for floating-point arithmetic that a assume that arguments and results are valid and b may violate IEEE or ANSI standards. When used at link time, it may include libraries or startup files that change the default FPU control word or other similar optimizations.

Enables -fno-signed-zeros , -fno-trapping-math , -fassociative-math and -freciprocal-math. Allow re-association of operands in series of floating-point operations. May also reorder floating-point comparisons and thus may not be used when ordered comparisons are required. This option requires that both -fno-signed-zeros and -fno-trapping-math be in effect.

For Fortran the option is automatically enabled when both -fno-signed-zeros and -fno-trapping-math are in effect. Allow the reciprocal of a value to be used instead of dividing by the value if this enables optimizations.

Note that this loses precision and increases the number of flops operating on the value. Allow optimizations for floating-point arithmetic that ignore the signedness of zero. Compile code assuming that floating-point operations cannot generate user-visible traps. These traps include division by zero, overflow, underflow, inexact result and invalid operation. This option requires that -fno-signaling-nans be in effect. Disable transformations and optimizations that assume default floating-point rounding behavior.

This is round-to-zero for all floating point to integer conversions, and round-to-nearest for all other arithmetic truncations. This option should be specified for programs that change the FP rounding mode dynamically, or that may be executed with a non-default rounding mode.

This option disables constant folding of floating-point expressions at compile time which may be affected by rounding mode and arithmetic transformations that are unsafe in the presence of sign-dependent rounding modes. This option is experimental and does not currently guarantee to disable all GCC optimizations that are affected by rounding mode. Compile code assuming that IEEE signaling NaNs may generate user-visible traps during floating-point operations. Setting this option disables optimizations that may change the number of exceptions visible with signaling NaNs.

This option implies -ftrapping-math. This option is experimental and does not currently guarantee to disable all GCC optimizations that affect signaling NaN behavior. The default is -ffp-int-builtin-inexact , allowing the exception to be raised, unless C2X or a later C standard is selected.

This option does nothing unless -ftrapping-math is in effect. Treat floating-point constants as single precision instead of implicitly converting them to double-precision constants.

When enabled, this option states that a range reduction step is not needed when performing complex division. The default is -fno-cx-limited-range , but is enabled by -ffast-math. Nevertheless, the option applies to all languages. Complex multiplication and division follow Fortran rules.

The following options control optimizations that may improve performance, but are not enabled by any -O options. This section includes experimental options that may produce broken code. After running a program compiled with -fprofile-arcs see Instrumentation Options , you can compile it a second time using -fbranch-probabilities , to improve optimizations based on the number of times each branch was taken.

When a program compiled with -fprofile-arcs exits, it saves arc execution counts to a file called sourcename. gcda for each source file. The information in this data file is very dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations. See details about the file naming in -fprofile-arcs.

These can be used to improve optimization. Currently, they are only used in one place: in reorg. If combined with -fprofile-arcs , it adds code so that some data about values of expressions in the program is gathered. With -fbranch-probabilities , it reads back the data gathered from profiling values of expressions for usage in optimizations. Enabled by -fprofile-generate , -fprofile-use , and -fauto-profile. Function reordering based on profile instrumentation collects first time of execution of a function and orders these functions in ascending order.

If combined with -fprofile-arcs , this option instructs the compiler to add code to gather information about values of expressions. With -fbranch-probabilities , it reads back the data gathered and actually performs the optimizations based on them. Currently the optimizations include specialization of division operations using the knowledge about the value of the denominator.

Attempt to avoid false dependencies in scheduled code by making use of registers left over after register allocation. This optimization most benefits processors with lots of registers. Performs a target dependent pass over the instruction stream to schedule instructions of same type together because target machine can execute them more efficiently if they are adjacent to each other in the instruction flow. Perform tail duplication to enlarge superblock size. This transformation simplifies the control flow of the function allowing other optimizations to do a better job.

Unroll loops whose number of iterations can be determined at compile time or upon entry to the loop. It also turns on complete loop peeling i. complete removal of loops with a small constant number of iterations. This option makes code larger, and may or may not make it run faster. Unroll all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly. Peels loops for which there is enough information that they do not roll much from profile feedback or static analysis.

complete removal of loops with small constant number of iterations. Enables the loop invariant motion pass in the RTL loop optimizer. Enabled at level -O1 and higher, except for -Og.

Enables the loop store motion pass in the GIMPLE loop optimizer. This moves invariant stores to after the end of the loop in exchange for carrying the stored value in a register across the iteration. Note for this option to have an effect -ftree-loop-im has to be enabled as well. Move branches with loop invariant conditions out of the loop, with duplicates of the loop on both branches modified according to result of the condition.

If a loop iterates over an array with a variable stride, create another version of the loop that assumes the stride is always one.

This is particularly useful for assumed-shape arrays in Fortran where for example it allows better vectorization assuming contiguous accesses. Place each function or data item into its own section in the output file if the target supports arbitrary sections. Use these options on systems where the linker can perform optimizations to improve locality of reference in the instruction space. Most systems using the ELF object format have linkers with such optimizations.

On AIX, the linker rearranges sections CSECTs based on the call graph. The performance impact varies. Together with a linker garbage collection linker --gc-sections option these options may lead to smaller statically-linked executables after stripping.

Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker create larger object and executable files and are also slower. These options affect code generation. They prevent optimizations by the compiler and assembler using relative locations inside a translation unit since the locations are unknown until link time.

An example of such an optimization is relaxing calls to short call instructions. This transformation can help to reduce the number of GOT entries and GOT accesses on some targets. usually calculates the addresses of all three variables, but if you compile it with -fsection-anchors , it accesses the variables from a common anchor point instead.

Zero call-used registers at function return to increase program security by either mitigating Return-Oriented Programming ROP attacks or preventing information leakage through registers. The rules that follow describe how non-negative numbers are output. The primary format token is always present and must not be zero-length. If the string contains one or more semicolons then everything that precedes the last semicolon is taken as the primary format token and everything that follows is taken as the format modifier; if the string contains no semicolon then the entire picture is taken as the primary format token, and the format modifier is taken to be absent which is equivalent to supplying a zero-length string.

A decimal-digit-pattern made up of optional-digit-signs , mandatory-digit-signs , and grouping-separator-signs. A mandatory-digit-sign is a · character · in Unicode category Nd. All mandatory-digit-signs within the format token must be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode category Nd , having digit values 0 through 9.

Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by , , or a grouping-separator-sign is a non-alphanumeric character, that is a · character · whose Unicode category is other than Nd , Nl , No , Lu , Ll , Lt , Lm or Lo. If it contains a digit but does not match this pattern, a dynamic error is raised [ err:FODF ].

If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier. There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs , and if present these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the decimal-digit-pattern , nor adjacent to another grouping-separator-sign.

The corresponding output format is a decimal number, using this digit family, with at least as many digits as there are mandatory-digit-signs in the format token. Thus, a format token 1 generates the sequence 0 1 The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the grouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.

More specifically, the position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.

Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator. The grouping separator template is a possibly infinite set of position, character pairs. If grouping separators are regular, then the grouping separator template contains one pair of the form n×G, C for every positive integer n where G is the grouping size and C is the grouping character.

Otherwise when grouping separators are not regular , the grouping separator template contains one pair of the form P, C for every grouping separator found in the primary formatting token, where C is the grouping separator character and P is its position.

If there are no grouping separators, then the grouping separator template is an empty set. Let S 1 be the result of formatting the supplied number in decimal notation as if by casting it to xs:string.

Let S 2 be the result of padding S 1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatory-digit-signs in the primary format token.

Let S 3 be the result of replacing all decimal digits in S 2 with the corresponding digits from the selected digit family. Let S 4 be the result of inserting grouping separators into S 3 : for every position P , character C pair in the grouping separator template where P is less than the number of digits in S 3 , insert character C into S 3 at position P , counting from the right-hand end.

Let S 5 be the result of converting S 4 into ordinal form, if an ordinal modifier is present, as described below. The format token A , which generates the sequence A B C Z AA AB AC The format token a , which generates the sequence a b c z aa ab ac The format token i , which generates the sequence i ii iii iv v vi vii viii ix x The format token I , which generates the sequence I II III IV V VI VII VIII IX X The format token w , which generates numbers written as lower-case words, for example in English, one two three four The format token W , which generates numbers written as upper-case words, for example in English, ONE TWO THREE FOUR The format token Ww , which generates numbers written as title-case words, for example in English, One Two Three Four Any other format token, which indicates a numbering sequence in which that token represents the number 1 one but see the note below.

It is · implementation-defined · which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1. In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example see also the example below is classical Greek where a dexia keraia x, ʹ and sometimes an aristeri keraia x, ͵ is added.

For all format tokens other than a decimal-digit-pattern , there may be · implementation-defined · lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits.

For the numbering sequences described above any upper bound imposed by the implementation must not be less than one thousand and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1. The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written for example, IV versus IIII as the representation of the number 4.

Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits. Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w , W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter x Cyrillic capital letter A.

If the argument is specified, the value should be either an empty sequence or a value that would be valid for the xml:lang attribute see [Extensible Markup Language XML 1. Note that this permits the identification of sublanguages based on country codes from ISO as well as identification of dialects and regions within a country.

The set of languages for which numbering is supported is · implementation-defined ·. That is, if it is present it must consist of one or more of the following, in order:. either c or o , optionally followed by a sequence of characters enclosed between parentheses, to indicate cardinal or ordinal numbering respectively, the default being cardinal numbering.

either a or t , to indicate alphabetic or traditional numbering respectively, the default being · implementation-defined ·. If the o modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token 1 , this outputs the sequence 1st 2nd 3rd 4th The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences.

The interpretation of this string is · implementation-defined ·. No error occurs if the implementation does not define any interpretation for the defined string. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.

The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language.

In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is · implementation-defined ·. A dynamic error is raised [ err:FODF ] if the format token is invalid, that is, if it violates any mandatory rules indicated by an emphasized must or required keyword in the above rules.

For example, the error is raised if the primary format token contains a digit but does not match the required regular expression. Note the careful distinction between conditions that are errors and conditions where fallback occurs.

The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.

If grouping-separator-signs appear at regular intervals within the format token, then the sequence is extrapolated to the left, so grouping separators will be used in the formatted number at every multiple of N.

For example, if the format token is 0' then the number one million will be formatted as 1'' , while the number fifteen will be formatted as 0' The only purpose of optional-digit-signs is to mark the position of grouping-separator-signs. For example, if the format token is ' 0 then the number one million will be formatted as 1'' , while the number fifteen will be formatted as A grouping separator is included in the formatted number only if there is a digit to its left, which will only be the case if either a the number is large enough to require that digit, or b the number of mandatory-digit-signs in the format token requires insignificant leading zeros to be present.

Grouping separators are not designed for effects such as formatting a US telephone number as In general they are not suitable for such purposes because a only single characters are allowed, and b they cannot appear at the beginning or end of the number.

Numbers will never be truncated. Given the decimal-digit-pattern 01 , the number three hundred will be output as , despite the absence of any optional-digit-sign. In some languages, the form of numbers especially ordinal numbers varies depending on the grammatical context: they may have different genders and may decline with the noun that they qualify.

In such cases the string appearing in parentheses after the letter c or o may be used to indicate the variation of the cardinal or ordinal number required. The way in which the variation is indicated will depend on the conventions of the language. For inflected languages that vary the ending of the word, the approach recommended in the previous version of this specification was to indicate the required ending, preceded by a hyphen: for example in German, appropriate values might be o -e , o -er , o -es , o -en.

format-integer , 'w' might return "one hundred and twenty-three". format-integer 14, 'Ww;o -e ', 'de' might return "Vierzehnte". This function can be used to format any numeric quantity, including an integer.

For integers, however, the fn:format-integer function offers additional possibilities. Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification.

XSLT and XQuery both provide custom syntax for creating a decimal format. The static context provides a set of decimal formats.

One of the decimal formats is unnamed, the others if any are identified by a QName. There is always an unnamed decimal format available, but its contents are · implementation-defined ·. Each decimal format provides a set of named properties, described in the following table:. A phrase such as "The minus-sign XP31 character" is to be read as "the character assigned to the minus-sign XP31 property in the relevant decimal format within the static context".

For any named or unnamed decimal format, the properties representing characters used in a · picture string · must have distinct values. These properties are decimal-separator XP31 , grouping-separator XP31 , exponent-separator XP31 , percent XP31 , per-mille XP31 , digit XP31 , and pattern-separator XP Furthermore, none of these properties may be equal to any · character · in the · decimal digit family ·. Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.

The two-argument form of this function is · deterministic · , · context-independent · , and · focus-independent ·. The three-argument form of this function is · deterministic · , · context-dependent · , and · focus-independent ·. It depends on decimal formats, and namespaces. The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument. The syntax of the picture string is described in 4. Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double , as such promotion can involve a loss of precision.

A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used no prefix means no namespace. A URIQualifiedName using the syntax Q{uri}local , where the URI can be zero-length to indicate a name in no namespace. The evaluation of the fn:format-number function takes place in two phases, an analysis phase described in 4.

The analysis phase takes as its inputs the · picture string · and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

The result of the function is the formatted string representation of the supplied number. If the processor is able to detect the error statically for example, when the argument is supplied as a string literal , then the processor may optionally signal this as a static error.

A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium.

Both in the picture string and in the result string, digits with higher significance that is, representing higher powers of ten always precede digits with lower significance, even when the rendered text flow is from right to left.

The following examples assume a default decimal format in which the chosen digits are the ASCII digits , the decimal separator is ". The expression format-number The following example assumes the existence of a decimal format named 'ch' in which the grouping separator is ʹ and the decimal separator is · :. The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':.

The expression format-number 0. This differs from the format-number function previously defined in XSLT 2. The digits will all be from the same decimal digit family, specifically, the sequence of ten consecutive digits starting with the digit assigned to the zero-digit property.

This change is to align format-number which previously used '' with format-dateTime which used ''. The picture string is a sequence of · characters · , in which the characters assigned to the properties decimal-separator XP31 , exponent-separator XP31 , grouping-separator XP31 , and digit XP31 , and pattern-separator XP31 and the members of the · decimal digit family · , are classified as active characters, and all other characters including the values of the properties percent XP31 and per-mille XP31 are classified as passive characters.

A dynamic error is raised [ err:FODF ] if the · picture string · does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".

A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separator XP31 character. A picture-string must not contain more than one instance of the pattern-separator XP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values. A sub-picture must not contain more than one instance of the decimal-separator XP31 character.

A sub-picture must not contain more than one instance of the percent XP31 or per-mille XP31 characters, and it must not contain one of each.

The mantissa part of a sub-picture defined below must contain at least one character that is either an · optional digit character · or a member of the · decimal digit family ·.

A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character. A sub-picture must not contain a grouping-separator XP31 character that appears adjacent to a decimal-separator XP31 character, or in the absence of a decimal-separator XP31 character, at the end of the integer part.

A sub-picture must not contain two adjacent instances of the grouping-separator XP31 character. The integer part of a sub-picture defined below must not contain a member of the · decimal digit family · that is followed by an instance of the · optional digit character ·. The fractional part of a sub-picture defined below must not contain an instance of the · optional digit character · that is followed by a member of the · decimal digit family ·.

A character that matches the exponent-separator XP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign. A sub-picture that contains a percent XP31 or per-mille XP31 character must not contain a character treated as an exponent-separator-sign.

If a sub-picture contains a character treated as an exponent-separator-sign then this must be followed by one or more characters that are members of the · decimal digit family · , and it must not be followed by any active character that is not a member of the · decimal digit family ·.

The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign ; if there is no exponent-separator-sign then the exponent part is absent.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator XP31 character if there is one, or the entire mantissa part otherwise. The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-separator XP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise.

The fractional part may be zero-length. This phase of the algorithm analyzes the · picture string · and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase.

These variables are listed below. Each is shown with its initial setting and its datatype. Several variables are associated with each sub-picture.

If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive and unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture. The integer-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture.

For each grouping-separator XP31 character that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of · optional digit character · and · decimal digit family · characters that appear within the integer part of the sub-picture and to the right of the grouping-separator XP31 character.

There is a positive integer G the grouping size such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple of G.

Every position in the integer part of the sub-picture that is a positive integer multiple of G is occupied by a grouping-separator. If the grouping is regular, then the integer-part-grouping-positions sequence contains all integer multiples of G as far as necessary to accommodate the largest possible number. The minimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator character.

It is initially set to the number of · decimal digit family · characters found in the integer part of the sub-picture, but may be adjusted as described below. There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of · optional digit character · and · decimal digit family · characters in the subpicture.

The scaling factor is a non-negative integer used to determine the scaling of the mantissa in exponential notation.

It is set to the number of · decimal digit family · characters found in the integer part of the sub-picture. The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-sign XP31 character and the prefix for the positive sub-picture if any , in that order. The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture.

For each grouping-separator XP31 character that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of · optional digit character · and · decimal digit family · characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator XP31 character.

There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of · optional digit character · and · decimal digit family · characters in the fractional part of the sub-picture.

The minimum-fractional-part-size is set to the number of · decimal digit family · characters found in the fractional part of the sub-picture.

The maximum-fractional-part-size is set to the total number of · optional digit character · and · decimal digit family · characters found in the fractional part of the sub-picture. If the effect of the above rules is that minimum-integer-part-size and maximum-fractional-part-size are both zero, then an adjustment is applied as follows:.

This has the effect that with the picture. e9 , the value 0. This has the effect that with the picture , the value 0. There is at least one · optional digit character · in the integer part of the sub-picture. If after making the above adjustments the minimum-integer-part-size and the minimum-fractional-part-size are both zero, then the minimum-fractional-part-size is set to 1 one. The minimum-exponent-size is set to the number of · decimal digit family · characters found in the exponent part of the sub-picture if present, or zero otherwise.

The rules for the syntax of the picture string ensure that if an exponent separator is present, then the minimum-exponent-size will always be greater than zero. The suffix is set to contain all passive characters to the right of the rightmost active character in the sub-picture. If there is only one sub-picture, then all variables for positive numbers and negative numbers will be the same, except for prefix : the prefix for negative numbers will be preceded by the minus-sign XP31 character.

This section describes the second phase of processing of the fn:format-number function. This phase takes as input a number to be formatted referred to as the input number , and the variables set up by analyzing the decimal format in the static context and the · picture string · , as described above.

The result of this phase is a string, which forms the return value of the fn:format-number function. If the input number is NaN not a number , the result is the value of the pattern separator XP31 property with no prefix or suffix.

In the rules below, the positive sub-picture and its associated variables are used if the input number is positive, and the negative sub-picture and its associated variables are used if it is negative. For xs:double and xs:float , negative zero is taken as negative, positive zero as positive.

For xs:decimal and xs:integer , the positive sub-picture is used for zero. If the sub-picture contains a percent XP31 character, the adjusted number is the input number multiplied by If the sub-picture contains a per-mille XP31 character, the adjusted number is the input number multiplied by If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.

If the adjusted number is positive or negative infinity, the result is the concatenation of the appropriate prefix , the value of the infinity XP31 property, and the appropriate suffix. If the minimum exponent size is non-zero, then the adjusted number is scaled to establish a mantissa and an integer exponent.

The mantissa and exponent are chosen such that all the following conditions are true:. The primitive type of the mantissa is the same as the primitive type of the adjusted number integer, decimal, float, or double. The mantissa multiplied by ten to the power of the exp onent is equal to the adjusted number. The mantissa is less than 10 N , and at least 10 N-1 , where N is the scaling factor.

If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent. The mantissa is converted if necessary to an xs:decimal value, using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets. If there are several such values that are numerically equal to the mantissa bearing in mind that if the mantissa is an xs:double or xs:float , the comparison will be done by converting the decimal value back to an xs:double or xs:float , the one that is chosen should be one with the smallest possible number of digits not counting leading or trailing zeroes whether significant or insignificant.

For example, 1. This value is then rounded so that it uses no more than maximum-fractional-part-size digits in its fractional part. The rounded number is defined to be the result of converting the mantissa to an xs:decimal value, as described above, and then calling the function fn:round-half-to-even with this converted number as the first argument and the maximum-fractional-part-size as the second argument, again with no limits on the totalDigits or fractionDigits in the result.

The absolute value of the rounded number is converted to a string in decimal notation, using the digits in the · decimal digit family · to represent the ten decimal digits, and the decimal-separator XP31 character to separate the integer part and the fractional part. This string must always contain a decimal-separator XP31 , and it must contain no leading zeroes and no trailing zeroes.

The value zero will at this stage be represented by a decimal-separator XP31 on its own. If the number of digits to the left of the decimal-separator XP31 character is less than minimum-integer-part-size , leading zero digit XP31 characters are added to pad out to that size. If the number of digits to the right of the decimal-separator XP31 character is less than minimum-fractional-part-size , trailing zero digit XP31 characters are added to pad out to that size.

For each integer N in the integer-part-grouping-positions list, a grouping-separator XP31 character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separator XP31 character, if there is such a digit. For each integer N in the fractional-part-grouping-positions list, a grouping-separator XP31 character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separator XP31 character, if there is such a digit.

If there is no decimal-separator XP31 character in the sub-picture, or if there are no digits to the right of the decimal-separator character in the string, then the decimal-separator character is removed from the string it will be the rightmost character in the string.

If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: a the exponent-separator XP31 character; b if the exponent is negative, the minus-sign XP31 character; c the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size , using digits taken from the · decimal digit family ·.

The result of the function is the concatenation of the appropriate prefix , the string conversion of the number as obtained above, and the appropriate suffix. The functions in this section perform trigonometric and other mathematical calculations on xs:double values. They are provided primarily for use in applications performing geometrical computation, for example when generating SVG graphics.

Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent.

Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.

The functions in this section with the exception of math:pi are specified by reference to [IEEE ] , where they appear as Recommended operations in section 9. IEEE defines these functions for a variety of floating point formats; this specification defines them only for xs:double values. The IEEE specification applies with the following caveats:. IEEE states that the preferred quantum is language-defined.

In this specification, it is · implementation-defined ·. IEEE states that certain functions should raise the inexact exception if the result is inexact. In this specification, this exception if it occurs does not result in an error. Any diagnostic information is outside the scope of this specification. IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined.

In this specification, the rounding direction and any mechanisms for influencing it are · implementation-defined ·. Certain operations such as taking the square root of a negative number are defined in IEEE to signal the invalid operation exception and return a quiet NaN. In this specification, such operations return NaN and do not raise an error. The same policy applies to operations such as taking the logarithm of zero that raise a divide-by-zero exception.

Operations whose mathematical result is greater than the largest finite xs:double value are defined in IEEE to signal the overflow exception; operations whose mathematical result is closer to zero than the smallest non-zero xs:double value are similarly defined in IEEE to signal the underflow exception.

The treatment of these exceptions in this specification is defined in 4. Returns an approximation to the mathematical constant π. This function returns the xs:double value whose lexical representation is 3. The treatment of overflow and underflow is defined in 4. The expression math:exp 1 returns 2. The treatment of divideByZero and invalidOperation exceptions is defined in 4. The effect is that if the argument is zero, the result is -INF , and if it is negative, the result is NaN.

The treatment of the divideByZero and invalidOperation exceptions is defined in 4. Some of the consequences are illustrated in the examples below. The expression math:pow -0e0, Odd-valued whole numbers are treated specially.

The expression math:pow -0e0, 3. The expression math:pow The treatment of the invalidOperation exception is defined in 4.

The effect is that if the argument is less than zero, the result is NaN. Negative zero is the only case where the result can have negative sign. The treatment of the invalidOperation and underflow exceptions is defined in 4.

The expression math:sin math:pi div 2 returns 1. The expression math:sin -math:pi div 2 returns The expression math:cos math:pi div 2 returns 0. The expression math:cos -math:pi div 2 returns 0. The expression math:tan math:pi div 4 returns 1. The expression math:tan -math:pi div 4 returns The expression 1 div math:tan math:pi div 2 returns 0.

But because math:pi div 2 returns an approximation, the result of math:tan math:pi div 2 will be a large but finite number. The expression 1 div math:tan -math:pi div 2 returns But because -math:pi div 2 returns an approximation, the result of math:tan -math:pi div 2 will be a large but finite negative number. The expression math:asin 1. The expression math:asin The expression math:acos 0 returns 1. The expression math:acos The treatment of the underflow exception is defined in 4.

The expression math:atan 1. The expression math:atan The expression math:atan xs:double 'INF' returns 1. The expression math:atan xs:double '-INF' returns Returns the angle in radians subtended at the origin by the point on a plane with coordinates x, y and the positive x-axis.

The result is the value of atan2 y, x as defined in the [IEEE ] specification of the atan2 function applied to bit binary floating point values. The expression math:atan2 Returns a random number generator, which can be used to generate sequences of random numbers. This function is · deterministic · , · context-independent · , · focus-independent · , and · higher-order ·.

The function returns a random number generator. A random number generator is represented as a map containing three entries.

Below is list of command-line options recognized by the ImageMagick command-line tools. If you want a description of a particular option, click on the option name in the navigation bar above and you will go right to it.

Unless otherwise noted, each option is recognized by the commands: convert and mogrify. A Gaussian operator of the given radius and standard deviation sigma is used. If sigma is not given it defaults to 1. The sigma value is the important argument, and determines the actual amount of blurring that will take place.

The radius is only used to determine the size of the array which holds the calculated Gaussian distribution. It should be an integer. If not given, or set to zero, IM will calculate the largest possible radius that will provide meaningful results for the Gaussian distribution.

See Image Geometry for complete details about the geometry argument. The -adaptive-resize option defaults to data-dependent triangulation. Use the -filter to choose a different resampling algorithm.

Offsets, if present in the geometry string, are ignored, and the -gravity option has no effect. This option is enabled by default. An attempt is made to save all images of an image sequence into the given output file.

However, some formats, such as JPEG and PNG, do not support more than one image per file, and in that case ImageMagick is forced to write each image as a separate file.

As such, if more than one image needs to be written, the filename given is modified by adding a -scene number before the suffix, in order to make distinct names for each image. As an example, the command. will create a sequence of 17 images the two given plus 15 more created by -morph , named: my00morph.

jpg, my01morph. jpg, my02morph. In summary, ImageMagick tries to write all images to one file, but will save to multiple files, if any of the following conditions exist Set the drawing transformation matrix for combined rotating and scaling. This option sets a transformation matrix, for use by subsequent -draw or -transform options.

The matrix entries are entered as comma-separated numeric values either in quotes or without spaces. Internally, the transformation matrix has 3x3 elements, but three of them are omitted from the input because they are constant.

The new transformed coordinates x' , y' of a pixel at position x , y in the original image are calculated using the following matrix equation.

The size of the resulting image is that of the smallest rectangle that contains the transformed source image. The parameters t x and t y subsequently shift the image pixels so that those that are moved out of the image area are cut off. The transformation matrix complies with the left-handed pixel coordinate system: positive x and y directions are rightward and downward, resp. If the translation coefficients t x and t y are omitted they default to 0,0.

Therefore, four parameters suffice for rotation and scaling without translation. Scaling by the factors s x and s y in the x and y directions, respectively, is accomplished with the following. See -transform , and the -distort method ' Affineprojection for more information. Translation by a displacement t x , t y is accomplished like so:. The cumulative effect of a sequence of -affine transformations can be accomplished by instead by a single -affine operation using the matrix equal to the product of the matrices of the individual transformations.

An attempt is made to detect near-singular transformation matrices. If the matrix determinant has a sufficiently small absolute value it is rejected. Used to set a flag on an image indicating whether or not to use existing alpha channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument type from the list below. This is a convenience for annotating an image with text.

For more precise control over text annotations, use -draw. The values Xdegrees and Ydegrees control the shears applied to the text, while t x and t y are offsets that give the location of the text relative any -gravity setting and defaults to the upper left corner of the image.

Using -annotate degrees or -annotate degrees x degrees produces an unsheared rotation of the text. The direction of the rotation is positive, which means a clockwise rotation if degrees is positive. This conforms to the usual mathematical convention once it is realized that the positive y —direction is conventionally considered to be downward for images. The new transformed coordinates x' , y' of a pixel at position x , y in the image are calculated using the following matrix equation.

If t x and t y are omitted, they default to 0. This makes the bottom-left of the text becomes the upper-left corner of the image, which is probably undesirable. Adding a -gravity option in this case leads to nice results. Text is any UTF-8 encoded character sequence. If text is of the form ' mytext.

txt', the text is read from the file mytext. Text in a file is taken literally; no embedded formatting characters are recognized. By default, objects e. text, lines, polygons, etc. are antialiased when drawn. This will then reduce the number of colors added to an image to just the colors being directly drawn.

That is, no mixed colors are added when drawing such objects. This option creates a single longer image, by joining all the current images in sequence top-to-bottom.

If they are not of the same width, narrower images are padded with the current -background color setting, and their position relative to each other can be controlled by the current -gravity setting. For more flexible options, including the ability to add space between images, use -smush.

Use this option to supply a password for decrypting a PDF that has been encrypted using Microsoft Crypto API MSC API. The encrypting using the MSC API is not supported. For a different encryption method, see -encipher and -decipher. This works well for real-life images with little or no extreme dark and light areas, but tend to fail for images with large amounts of bright sky or dark shadows. It also does not work well for diagrams or cartoon like images.

It uses the -channel setting, including the ' sync ' flag for channel synchronization , to determine which color values is used and modified. As the default -channel setting is ' RGB,sync ', channels are modified together by the same gamma value, preserving colors.

This is a 'perfect' image normalization operator. It finds the exact minimum and maximum color values in the image and then applies a -level operator to stretch the values to the full range of values. On the other hand it is the right operator to use for color stretching gradient images being used to generate Color lookup tables, distortion maps, or other 'mathematically' defined images.

The operator is very similar to the -normalize , -contrast-stretch , and -linear-stretch operators, but without 'histogram binning' or 'clipping' problems that these operators may have.

That is -auto-level is the perfect or ideal version these operators. It uses the -channel setting, including the special ' sync ' flag for channel synchronization , to determine which color values are used and modified. Adjusts an image so that its orientation is suitable for viewing i. top-left orientation. This operator reads and resets the EXIF image profile setting 'Orientation' and then performs the appropriate 90 degree rotation on the image to orient the image, for correct viewing.

This EXIF profile setting is usually set using a gravity sensor in digital camera, however photos taken directly downward or upward may not have an appropriate value. Also images that have been orientation 'corrected' without reseting this setting, may be 'corrected' again resulting in a incorrect result. If the EXIF profile was previously stripped, the -auto-orient operator will do nothing.

The computed threshold is returned as the auto-threshold:verbose image property. This backdrop covers the entire workstation screen and is useful for hiding other X window activity while viewing the image.

The color of the backdrop is specified as the background color. The color is specified using the format described under the -fill option. The default background color if none is specified or found in the image is white.

Repeat the entire command for the given number of iterations and report the user-time and elapsed time. For instance, consider the following command and its output. Modify the benchmark with the -duration to run the benchmark for a fixed number of seconds and -concurrent to run the benchmark in parallel requires the OpenMP feature.

In this example, 5 iterations were completed at 2. This option shifts the output of -convolve so that positive and negative results are relative to the specified bias value. This is important for non-HDRI compilations of ImageMagick when dealing with convolutions that contain negative as well as positive values.

This is especially the case with convolutions involving high pass filters or edge detection. Without an output bias, the negative values are clipped at zero. See the discussion on HDRI implementations of ImageMagick on the page High Dynamic-Range Images. For more about HDRI go the ImageMagick Usage pages or this Wikipedia entry. A non-linear, edge-preserving, and noise-reducing smoothing filter for images. It replaces the intensity of each pixel with a weighted average of intensity values from nearby pixels.

This weight is based on a Gaussian distribution.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. Use all loops as register allocation regions. Perform interprocedural scalar replacement of aggregates, removal of unused parameters and replacement of parameters passed by reference by parameters passed by value. To extract a profile, the -profile option is not used. See below. usually calculates the addresses of all three variables, but if you compile it with -fsection-anchors , it accesses the variables from a common anchor point instead. Conference Journal Proceedings Upcoming Conference Journal Proceedings Previous Conference Journal Proceedings.

Categories:

• Forex Bitcoin
• Binary Options
• Forex
• Forex Brokers
• Binary Options online