ImageMagick Examples --
Image Transformations

  magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \
          shade_circle_mask.gif
  magick shade_circle_mask.gif            -shade 120x45  shade_blur_0.gif
  magick shade_circle_mask.gif -blur 0x1  -shade 120x45  shade_blur_1.gif
  magick shade_circle_mask.gif -blur 0x2  -shade 120x45  shade_blur_2.gif
  magick shade_circle_mask.gif -blur 0x3  -shade 120x45  shade_blur_3.gif
  magick shade_circle_mask.gif -blur 0x4  -shade 120x45  shade_blur_4.gif
  magick shade_circle_mask.gif -blur 0x5  -shade 120x45  shade_blur_5.gif

magick shade_blur_3.gif -normalize shade_blur_3n.gif

magick shade_blur_3n.gif shade_circle_mask.gif \ -alpha Off -compose CopyOpacity -composite shade_blur_3n_mask.png

  magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \
          -blur 0x2  -shade 120x30           shade_30.png
  magick shade_30.png   -gravity center -crop 1x1+0+0 txt:-

  magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \
          -blur 0x2  -shade 120x30 -normalize   shade_30_norm.png
  magick shade_30_norm.png   -gravity center -crop 1x1+0+0 txt:-

  magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \
          -blur 0x2  -shade 120x21.78 -normalize   shade_21_norm.png
  magick shade_21_norm.png   -gravity center -crop 1x1+0+0 txt:-

magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \ \( +clone -blur 0x2 -shade 120x21.78 -normalize \) \ +swap -alpha Off -compose CopyOpacity -composite shade_tint_0.png magick shade_tint_0.png -fill grey50 -colorize 10% shade_tint_10.png magick shade_tint_0.png -fill grey50 -colorize 30% shade_tint_30.png magick shade_tint_0.png -fill grey50 -colorize 50% shade_tint_50.png magick shade_tint_0.png -fill grey50 -colorize 80% shade_tint_80.png

An alternative to just linearly tinting the highlight, is to reduce its general effect while preserving the extreme bright/dark spots of the highlight by using Sigmoidal Non-liner Contrastinstead. This should give a more 'natural' look to the highlight effect, and can make the highlight brighter, as if the surface was more reflective. However to make this technique more effective, we need make sure we do not have pure white and black colors in the shade result. This can be achieved by first using a "-contrast-stretch" of '0%' rather than "-normalize", and also de-normalizing that result by a small amount, as we did above. This may seem to be just adding complexity to the generation of the highlight overlay image, but emphasizing the bright spots in the highlight makes the extra processing worth the effort. For example... As you can see that the overall highlighting is reduced in intensity, but the bright spot from reflected light remains as bright as ever, just reduced in size. The result is a much more natural 'shiny' look to the shape. The only drawback with this technique is that a shadow 'spot' is also generated though this is often not as noticeable. Finally we can combine the a 'highlight spot' with a general highlight reduction to produce a highly configurable set of highlight overlay generator controls...

magick -size 50x50 xc:black -fill white -draw 'circle 25,25 20,10' \ \( +clone -blur 0x4 -shade 120x21.78 -contrast-stretch 0% \ +sigmoidal-contrast 7x50% -fill grey50 -colorize 10% \) \ +swap -alpha Off -compose CopyOpacity -composite shade_overlay.png

In summary, the above example has four separate controls...

"blur" : Rounding the shape edges (0.001=beveled 2=smoothed 10=rounded)

"shade" : The direction the light is coming from (120=top-left 60=top-right)

"sigmoidal" : surface reflective control highlight spots (1=flat 5=good 10=reflective )

"colorize" : Overall contrast of the highlight ( 0%=bright 10%=good 50%=dim )

Note while the above examples have been shaped to the original 'circle' shape, the transparency should only be restored AFTER 'Overlay' compositing has been applied, not before. Also if you plan to use a highlight repeatedly on the same shape (after any rotation is performed), you can pre-generate the highlight overlay once for each shape you plan to use, saving the result for multiple re-use. An example of this re-use of shading overlay is with the generation of 3D DVD covers from flat source images in the IM Discussion Forums. I also highly recommend you experiment with the above techniques, as they are key to making your flat shaped images, much more realistic looking. If you come up with other ideas for highlighting, please let me know.

FUTURE:
   Color Tinting the Overlay image
   Overlay Alpha Composition with an Image

Using a Dawn Shade Highlight

In Masking Shade Images above we showed how useful a 'mid-day' or 'high-noon' shade image (using an elevation of '90'), can be useful for masking and location and extent of the effects produced by "-shade. However the horizontal or 'dawn' shade images (using an elevation of '0')of a shape can also be quite useful as well. It can for example be used as a mask for either white or black images to generate separate highlight and shading effects on shapes. This also can be used ensure a shape gets roughly equal amounts of light and dark areas (or even unequal amounts), as I produce them in seperatally but in a completely controled way.

FUTURE: more detail here

See the first Advanced 3D Logo for an example of using this technique.

---

Using FX, The DIY Image Operator

The image list operator "-fx" is a general DIY operator that does not fit into any specific category of IM operators, as it can be used to create just about any image operation. Examples of its use are thought these pages, but here we will look specifically at its capabilities and how you can use them. The command is so generic in its abilities, that it can,

• create canvases, gradients, mathematical colormaps.
• move color values between images and channels.
• adjust image colors in just about any way imaginable
• translate, flip, mirror, rotate, scale, shear and generally distort images.
• merge or composite multiple images together.
• tile image(s) in weird and wonderful ways.
• convolve or merge neighboring pixels together.
• generate image metrics or 'fingerprints'
• compare images in unusual ways.

Of course many of these techniques are already part of IM, producing a faster and more flexible result. But if it isn't built-in the "-fx" allows you to generate your own version of the desired operation. In fact I and others have often used it to prototype new operations that are later built into IM's core library. As an example see DIY New Ordered Dither Replacement where I used "-fx" to develop a revised version of the -ordered-dither" operator. The operator is essentially allows you to perform free-form mathematical operations on one or more images. For the official summary of the command see FX, The Special Effects Image Operator on the ImageMagick Web Site.

FX Basic Usage

The command takes an image sequence of as many input images you like. Typically one or two images, and replaces ALL the input images with a copy of the first image, which has been modified by the results of the "-fx" function. That is, any meta-data that is in the first image will be preserved in the result of the "-fx" operator.For mathematical ease of use, all color values provided are normalized into a 0.0 to 1.0 range of values. Results are also expected to be in this range. This includes the transparency or alpha channel, which goes from 0.0 (meaning fully transparent) to 1.0 (meaning fully opaque). The values represent 'alpha transparency' and is actually the negative of how IM normally stores the transparency internally (as matte values). It is however more mathematically correct and easier to use in this form. The "-channel" setting defines what channel(s) in the first (also called the 'zeroth' or "u") image, is replaced with the result of the "-fx" operator. This is limited, by default, to just the color channels ('RGB') of the original image. Any existing transparency in that image will not be modified, unless the "-channel" setting is changed, to include the alpha ('A') channel. The expression is executed once for each pixel, as well an once for each color channel in the pixel that is being processed. Also as the expression is re-parsed each time it is executed, a complex expression could take some time to process on a large image. For example, here we define a black image, but then set the blue channel to be half-bright to form a 'navy blue' color instead.

magick -size 64x64 xc:black -channel blue -fx '1/2' fx_navy.gif

And here we we take a black-white gradient, and then set the blue and green channels to zero, so it becomes a black-red gradient.

magick -size 64x64 gradient:black-white \ -channel blue,green -fx '0' fx_red.gif

To make the "-channel" setting more like the "-fx" operator, it will accept any combinations of the letters 'RGBA' to specify the channels to which operators are to confine their actions. This means that to limit the output of "-fx" to just the blue and green channels you can now say "-channel BG" instead of the longer "-channel blue,green".

We could have generated the above examples without using "-fx", but being able to do this to an existing image is what makes this a powerful image operator. The function can in fact read and use ANY pixel, or specific color from ANY of the images already in the current image sequence in memory. The first 'zero' image, is given the special name of "u". The second image "v". Other images in memory can be referenced by an index. As such "u[3]" is the fourth image in the current image sequence, while "u[-1]" is the last image in the sequence. This is the same indexing scheme used by the Image List Operators, so you should be right at home. If no other qualifiers are given, the color value used is same color used in the image specified. That is, unless you specifically say you want to use the red color, it will use the color value for the color channel the command is processing at that time. That is, it will apply the expression for the blue color value when it is processing the blue channel. Unless told otherwise it will process each of the RGB color values (as set by the default "-channel" setting), for each and every pixel in the image. That is, 3*w*h calculations which modifies all the values in the image by the expression given. For example, here we take the IM built-in "rose:" image and multiply all pixel values by 50%.

magick rose: -fx 'u*1.5' fx_rose_brighten.gif

In the above example, each of the individual red, green and blue values was multiplied by 1.5. If the resulting value is outside the 0 to 1 range it, will be limited to the appropriate bound (1.0 in this case), unless you are using the default HDRI version of ImageMagick. Lots of other "-fx" formulas to recolor images are explored in Mathematical Color Adjustments and Histogram Curves. As we can also reference any image in the current image sequence, as part of the expression for modifing the first image, we can merge two, or even more images, in just about any way we want. Here we generate a black-red-blue color chart image, by copying the blue channel from a black-blue gradient (rotated), into the previous black-red gradient we generated above.

Of course we could have just used a Channel Coping Composition Method instead which would be a lot faster. But that is not point. Though the reverse is also true. Just about every IM image operation could be replaced by a FX equivelent function.

Now the second image in the above is only used as a source image. What really happens is that "-fx" first creates a copy of just the first image. It then modifies that image according to the formula, using all the other images given. And finally it junks all the input images replacing them with the modified copy of the first image. You can also calculate values based on each pixel location within the image. values 'i,j' is the current position of the pixel being processed, while 'w,h' gives the size of the image (the first image unless a specific image qualifier is given). For example, here we generate a DIY Gradient Image.

magick rose: -channel G -fx 'sin(pi*i/w)' -separate fx_sine_gradient.gif

Or something more complex using both 'i,j' position values. magick -size 80x80 xc: -channel G -fx 'sin((i-w/2)*(j-h/2)/w)/2+.5'\ -separate fx_2d_gradient.gif

When generating gray-scale gradients, you can make the -fx operator work about 3 times faster, simply by asking it to only process one color channel, such as the 'G' or green channel in the above example. This channel can then be Separated to generate the final gray-scale image. This can represent a very large speed boost, especially when using a very complex "-fx" formula. For more FX generated gradients, see examples Roll your own Gradients. You can use the position information to lookup specific pixels from the source image using the 'p{x,y}' syntax. For example you can easily make your own 'mirror image' type function (like the "-flop" image operator), that replaces each pixel, with the color values from the 'mirror' position of the original source.

magick rose: -fx 'p{w-i-1,j}' fx_rose_mirror.gif

This type of 'image distortion' was made more powerful by creating Distortion Image Mapping, or other types of Value Lookup Tables, in the form of images. Examples of doing this has been provided in DIY Dither Patterns and Threshold Maps, where FX is used to replace specific colors with patterns from other images. Now the size of the final image generated by an FX expression is the same as the first image given, as such to generate a larger image, you will need to set the first image to the size you want. In this type of situation a second image (or even a third image) can be used as a color source (hence the Swap in the next example). For example, here we resize rose image (using Interpolated Scaling or Resize) to generate a larger image.

magick rose: -size 120x80 xc: +swap \ -fx 'v.p{ (i+.5)*v.w/w-.5, (j+.5)*v.h/h-.5 }' \ fx_scaled.png

Note how the pixel lookup is performed, it may seem complex but it is the proper way to scale (distort) an image. Basically all the extra '0.5' values added to the expression is needed to correctly magick between Pixel Coodinates used for input coordinates 'i,j' and location lookup 'v.p{...}, while the more mathematically correct Image Coordinates is needed for the actual mathematical calculations (scaling). The above is actually the exact methodology used by any form of Image Distortion. You can see this FX equivelent for most distortions by turning on the Verbose Distortion Summery. This reports a FX equivelent for most image distortions, as a way to double check the distortion is doing what it is expected to do. The use of the FX DIY Operator to do image distortions, shows just how powerful this operator really is. If it wasn't for this operator I doubt may of the new operations, such as distortions, sparse-color, or ordered dithers would have been added to the ImageMagick Core Library. Here is something a little simplier, swapping the red and blue channels of the rose image. See if you can figure how it works.

magick rose: \( +clone -channel R -fx B \) \ +swap -channel B -fx v.R fx_rb_swap.gif

A faster and better way to do the same thing, is to use "-separate" and "-combine"). See Combining RGB Channel Images. Alternatively you can also use a "-color-matrix" to do the same thing faster still. Do you see a trend here?

As the default "-channel" setting, it limits the output of the "-fx" operator to just the three color channels. This means that if you want to effect the alpha or transparency channel, you must explicitly specify it, by changing the channel setting. For example lets make a semi-transparent "rose:" image, by setting all the alpha channel values to half.

magick rose: -alpha set -channel A -fx '0.5' fx_rose_trans.png

Note the for the above to work properly I needed to ensure that the "rose:" actually had an alpha channel for the "-fx" to work with. I did this with the Alpha Channel Control Operator. This ability of the "-fx" operator to manipulate the RGBA channels of an image makes this operator perfect for manipulating Channels and Masks.
As of IM 6.2.10 you can add variable assignments to "-fx" expressions, which allows you to reduce the complexity of some expressions, that would basically be impossible any other way. For example, here I create a gradient based on the distance from a particular point (assigned to the variables 'xx' and 'yy'). Without the use of the variables this formula could have become very hard to read.

magick -size 100x100 xc: -channel G \ -fx 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/70)*1.2+.5' \ -separate fx_radial_gradient.png

Due the simple tokenization handling used by "-fx", variable names can only consist of letters, and must not contain numbers. Also as a lot of single letters are used for internal variables accessing image information, it is recommended that variable names be at least two letters long. As such I use 'xx' and 'yy' rather than just 'x' or 'y'.

The "-fx" function 'rr=hypot(xx,yy)' was added to IM v6.3.6 to speed up the very commonly used expression 'rr=sqrt(xx*xx+yy*yy)'. Of course if you need the distance squared, you should avoid the 'hypot()' function, and the sqrt() function it implies.

For more examples of some really complex expressions see More Complex DIY Gradients, which would be impossible with out multiple statement assignments. The same is true for FX form of Perspective Distortion. As of IM version 6.3.0-1, the complexity of "-fx" expressions started to require external files, so the standard '@filename' can now be used to read the expression from a file.

echo "u*2" | magick rose: -fx "@-" fx_file.png

This also means you can use more complex scripts to generate the specific FX expressions for a particular job. Internally the file is simply read into a string and interpreted as usual. Other settings that are important to "-fx" are "-virtual-pixel" and "-interpolate". The Virtual Pixel Setting allows one to set what colors or image results should be returned when the lookup coordinates go outside the area covered by the input image. This allows one to set edge effects for things like blurs, as well as tile image over a larger area. The Interpolate Setting allows one to specify how IM should mix colors of neighbouring pixels when the lookup coordinates (floating point values) fall between the integer coordinates of the pixels in the input image. For more information see Interpolated Pixel Lookup.

Some More functions were added at various times IM v6.3.6 : hypot() IM v6.7.3-4 : while(), not(), guass(), squish()

FX Debugging

The 'debug(expr)' is essentially a way of printing a floating point value, each time the FX expression is calculated. This in turn provides a method of debugging your expressions. However you can limit the output from the "debug()" by using a tertiary if-else expression. For example this will print the floating point color values for pixel 10,10 from the built-in "rose:" image. The actual image result is ignored by using the 'NULL:' image handler.

magick rose: -fx 'i==10&&j==10?debug(u):1; u' null:

Remember the output is on standard error, not the normal standard output, that way you can use this in a command pipeline, without problems. Note how the FX expression was executed three times, once for each channel for just that one pixel. Multiply that by the number of pixels, and you can imagine the length of the output if "debug()" was not limited to just one pixel, even for this small image.

FX-like Built-in Operations

The -fx operator represents a way to develop new image processing functions that previously did not exist in ImageMagick. The result of such development by users has allows ImageMagick to expand, with new functions and methods, such as the Color Lookup Table ("-clut"). Generally however once a new method has stabilized using "-fx", the expression is converted into a faster built-in operation, usually added as part of a group of similar operators. These include the follow general image operator and there methods...

-evaluate	Direct pixel, color values, channel modification functions. (See Evaluate below).
-function	More Complex pixel, color value, channel modification functions. (See Function below).
-evaluate-sequence	Merge a multi-image sequence of images mathematically (See Evaluate-Sequence below).
-sparse-color	General Image Re-Coloring Operator. (See Sparse Color Gradients )
-compose	General Multi-Image combining and overlaying method. (See Alpha Composition).
-distort	General Image Distortion operator, using reversed pixel mapping. (See the Distort Operator )
-morphology	General Area Effect Convolution/Morphology function. (See the Morphology Operator and the Convolve Operator )

As people developed new types of image operations, they usually prototype it using a "-fx" operator first. When they have it worked out that 'method' is then converted into a new super-fast built-in operator in the ImageMagick Core library. Users are welcome to contribute their own "-fx" expressions (or other defined functions) that they feel would be an useful addition to IM, but which are not yet covered by other image operators, if they can be handled by one of the above generalized operators, it should be reasonably easy to add it. For example I myself needed a 'mask if color similar' type operation for comparing two images. This has been added as a new "-compose" method "ChangeMask". This in turn allowed me to then add a more complex Transparency Optimization for GIF animations. If "-fx" speed and complexity is starting to become a problem then it is probably better to move on to an API scripting language such as PerlMagick. An example of this using PerlMagick "pixel_fx.pl" is part of that API's distribution.

FX Expressions as Format and Annotate Escapes

As of IM version 6.2.10 you can now use FX Expressions within Image Property Escaped strings such as used by "-format" and "-annotate" arguments. The escape sequence '%[fx:...]' is replaced by a number as a floating point value, calculated once for each image in the current image sequence. The FX Expression however is modified slightly during processing. Specifically...

• The current pixel coordinates 'i', 'j' is fixed to the value 0, so on its own an image variable only returns the value from pixel 0,0, unless a 'p{}' index is used.
• Unless a color channel is selected only the red channel value is returned.
• The default image reference 's' is set to current image, being annotated or identified.
• The index 't' returns the index of the image referred to by 's'.

Before IM v6.6.8-6 both FX expression values of "t" image index and "n" total number of images, were broken, and only returned a value of 0 and 1 respectively for ALL images. The same goes for the equivalent percent escapes '%p' and '%n'.

For example, here I "-annotate" each image with the color of the top left corner of each image.

magick -size 150x25 xc:DarkRed xc:Green xc:Blue \ -fill white -gravity center \ -annotate 0 '%[fx:t] / %[fx:n] : %[fx:r],%[fx:g],%[fx:b]' \ annotate_fx_%d.gif

Notice how the text that is written is different for each image, as 'r' is actually equivalent to 's.p{0,0}.r'. The same goes for the 'g' and 'b' color channel values. Of course each one returns a normalized value in the range of 0.0 to 1.0. To make the output of specific pixel color values easier, a '%[pixel:...]' escape was also added in IM v6.3.0. This operator calls the given FX expression once for each channel in each image, and formats the returned value into a color that IM can handle as a color argument. You can just output the result directly using a "-format" with the "identify" command.

magick identify -format '%[fx:atan(1)*4]' null:

This will mathematically calculate and return the value of PI, though this value is available as the built-in variable 'pi'. You can generate random numbers. For example to generate an integer between -5 and 10 inclusive. Here I use the "info:" equivalent to the "magick identify" command.

magick xc: -format '%[fx:int(rand()*16)-5]' info:

For more methods see Identify Alternatives: Text Output Options. Also see Border with Rounded Corner which used a FX Expressions to generate a draw string based on image width and height information. You can Calculate Positions Images using FX formulas or even position using the size and location of other images (See Incrementally Calculated Positions). You can also use FX Escapes in Filename Percent Escapes to generate new files based on calculated values. For an example, see the final example in Tile Cropping.
All the above will essentially run the "-format" and thus any containing FX Expression one for each image in the current image sequence. The "-print" operator will work much like "-identify" except that it is only run once, with access to ALL the images in the current image sequence. With this operator you can use 'u[{i}]' to access values from any image, unlike the above.
Fx Expressions can be applied to images in other colorspaces, so I can for example find out the 'Hue' value (in the 'red' channel) for three different colors.

magick xc:red xc:green xc:blue -colorspace HSL \ -format '%[fx: s.r ]\n' info:

You can also use IM for some direct color maths, such as find out the average color of 'gold', 'yellow', and 'khaki'.

magick xc: -format '%[pixel:(gold+yellow+khaki)/3]' info:

While this shows what the color looks like compared to the three source colors...

magick xc:gold xc:yellow xc:khaki +append \ \( xc: -fx '(gold+yellow+khaki)/3' \) \ -scale 90x30\! -append fx_hues.png

You can also use "-print" to print information. This is applied only once against the whole image sequence. That means you can use this operator to calculate much more complex '%[fx:...]' expressions involving multiple images.

Accessing data from other images

There is one serious problem with using FX escaped expressions however. IM does not have direct access to the other images in the current image sequence when you are creating images. This is just generally not needed, in typical image creation, as new images generally do not depend on previous in-memory images. Basically if you want to gather the color of a specific pixel in a different image to the one you are drawing on (as above), or are creating a new image, then the IM core functions have no direct link to the desired info. For example if you try to create a label with the color of the built-in "rose:" image pixel 12,26 (a bluish pixel), the direct approach will fail!

magick rose: label:'%[pixel:p{12,26}]' -delete 0 label_fx_direct.gif

Well the rose image does not actually contain any black pixels, so the above result was wrong. The way to fix this is to extract the wanted information and save it into the global IM meta-data. This is passed to all sub-routines in the library core, including those for image creation.

magick rose: -set option:mylabel '%[pixel:u.p{12,26}]' -delete 0 \ label:'%[mylabel]' label_fx_indirect.gif

This is not intuitive but we now get the correct result. The special 'option:' tag, tells the "-set" option that you want the given setting saved as a global Artifact, rather than as an image 'Attribute' or 'Properties' string, just as "-define" can. However the "-set" form allows you to expand Percent Escapes in setting the Artifact, where as "-define" does not. When the "label:" operator expands its percent escapes, the given 'key' is looked for first as a per image 'attribute' or 'proprieties', but if it fails to find anything, it will then look for the 'key' in the global Artifact settings. As such the global 'artifact' we created from the previous image is used, even though that image is no longer present at the time the Artifact was created. Basically 'Artifact' settings are global during the life time of the "magick" command, and thus can be used to pass information from one image to another. For programmed API's this situation can be avoided as you can read the required data directly from the image and generate the label string yourself, without needing IM to store that information in such a convoluted way.

---

Evaluate and Function, Freeform Channel Modifiers

Because the FX Operator is an interpretted expression handler, the "-evaluate" operator was added to let you make simple image modifications more quickly. Later a more complex "-function" operator was added in IM v6.4.8-8, to allow greater flexibility in complex image adjustments. These two operators, along with other Image Level Adjustment Operators such as "-negate", "-level", will probably be most useful for minor tweaks to grey-scale images, before you apply those images. Especially in gray-scale images such as used for Background Removal, Highlight and Shadow Overlays, and the generation and fine-tuning of Image Maps.

Evaluate, Simple Math Operations

The "-evaluate" operator is basically a fast, but very simple version of "-fx" operator (actually pre-dates its addition to IM by just a couple of months). However it is limited to just one simple operation, using a single user provided constant number. You can find out what functions have been built into evaluate using This includes the typical mathematical functions 'add', 'subtract', 'multiply', and 'divide'. against constant values. Unlike the -fx operator the values are not normalised to a 0 to 1 range, but remain the real color values of the image. As such subtracting a value of 50 in a Q8 IM (See Quality and Depth will result in a large subtraction, but for a Q16 version of IM, it will only be a small hardly noticeable change. However if you add a '%' to the argument, that argument will represent a percentage of the maximum color value (known as 'QuantumRange' which is equal to ('2quality-1'). This means you can make your "-evaluate" arguments IM quality level independent, by the appropriate use of percentages for the appropriate evaluate methods. For example to just simply replace all color values in an image to a 50% gray level is very simple and very fast, using 'Set'

magick rose: -evaluate set 50% rose_set_gray.gif

The "-evaluate" operator also includes the typical mathematical functions 'add', 'subtract', 'multiply', and 'divide'. For example, to half the contrast of the image, you can 'divide' it by '2' then 'add' '25% to re-center it around a the perfect grey.

magick rose: -evaluate divide 2 -evaluate add 25% rose_de-constrast.gif

This is a couple of orders of magnitude faster than directly using the "-fx" operator with 'u/2+.25'. As such you should use this operator in preference to "-fx" if at all possible. The major problem with "-evaluate" is that all results are clipped to the 0 to 'QuantumRange' limits (unless you are using a HDRI version of ImageMagick), as each modified value is saved back into the image data. That means that after any individual "-evaluate" operation, the values could be clipped by the 'QuantumRange'. As such if you try to apply a contrast enhancement function (equivalent to "-fx '2*u-.25' ") directly as it stands, you will fail to get the correct results, as the doubled value will be clipped, before the subtraction is made.

magick rose: -evaluate multiply 2 -evaluate subtract 25% \ rose_contrast.gif

First the 'multiply' will clip all the large color values to the maximum value, then the 'subtract' will clip the lower bound values. the result is an incorrect clipping of the upper bounds, producing a dark and color distorted result. The direct solution is to 'subtract' the appropriate constant first (doing the final but correct clip of the lower bounds), before multiplying, effectively using the equivalent formula '(u-.125)*2'

magick rose: -evaluate subtract 12.5% -evaluate multiply 2 \ rose_contrast2.gif

However there are lots of alternatives to this 'clipping' problem. The first logical one being the newer Polynomial Function Method (see below). Other alternatives also include using Level Adjustment Operators or even a Level Adjustment by Color, to simply specify the original color values that you want to stretch out, to fill whole color range. Basically be careful with regards to color value clipping when using multiple "-evaluate" methods.
The "-evaluate" operator, like "-fx" (and most other low level IM operators) is "-channel" effected. This allows you to control an images alpha transparency separately to the color channels. And yes, like "-fx", transparency is treated as 'alpha values' and not a 'matte' value. For example to make an image 50% transparent, as part of a Dissolve type operation.

magick rose: -alpha set -channel A -evaluate divide 2 rose_transparent.png

The result is a semi-transparent image, which means when displayed, half the color you see is the web-pages background color. As such the image shown is dimmed toward the background color. Often I have also found that it is often easier to use "-evaluate" on the individual color channels before separating the various channels into separate images for specific purposes, (See Separating Channels). For example, here I use it to do a fast, but unusual form of gray-scaling. Basically I multiply each channel by the appropriate amount, then separate and add the channels together to produce an image that has been gray-scaled using a specific set of color ratios.

magick test.png -channel R -evaluate multiply .2 \ -channel G -evaluate multiply .5 \ -channel B -evaluate multiply .3 \ -channel RGB -separate -background black -compose plus -flatten gray_253.png

Evaluate Math Functions

Included in Evaluate, there are also a set of special purpose mathematical functions. These functions are implemented to generally use a normalized color value (0 to 1 range) with the output again normalized so as to fit the full color range of the image. The Sigmoidal Contrast function is also an example of this math function fitting.

Power Of

The 'Pow' function (added IM v6.4.1-9) for example works with normalized color values, and allows users to do image brightness modifications. It is exactly equivalent to the pow() C function, (using normalize color values in a 0 - 1 range)

    value = pow(value, constant) 

As such to create a 'parabolic' gradient you can use an argument of '2'. Or use a value of '0.5' to create a 'square root' gradient. For example...

The three lower images show the profile of the gradient produced both a graph and the original image itself. This makes it easier to see how one gradient image was modified to become another. It was generated using the Gnuplot graph ploting program, via the script "im_profile" in the IM Examples, Scripts directory.

This is actually equivalent to the Gamma Adjustment operator but with the argument inverted. For example a "-gamma 2" operation would be equivalent to an "-evaluate pow 0.5" or a 'square root' operation function. Similarly "-gamma 0.5" is equivelent to squaring using "-evaluate pow 2"By doing some special gradient manipulations, you can use this method to magick a linear gradient into a complex circular arc.

magick -size 20x300 gradient: -rotate 90 \ -evaluate Pow 2 -negate -evaluate Pow 0.5 \ -flop \( +clone -flop \) +append eval_circle_arc.png

For those wanting to figure this out, the second line in the above is equivelent to the FX expression 'sqrt(1-u^2)'. This generates a single quarter circle arc, which is then Flopped, and Appended together, to produce a half circular arc. It is also a lot faster than using an FX expression, even though it requires many more individual (smaller) steps. See also the more advanced Polynomial Function.

Logrithmic

The 'Log' function (added IM v6.4.2-1) also works with normalized values (with a 1.0 added to avoid infinities), with the given constant being used as the logarithmic base. The actual formula (with normalized values) is thus...

    value = log(value*constant+1.0)/log(constant+1.0) 

For example...

magick gradient.png -evaluate Log 10 eval_log.png

This may seem very simular to the previous Pow Evaluate Method, but it isn't quite the same. 'Log' will produce an appreciable slope as it approaches '0', where 'Pow' will produce a vertial slope. The value controls the slope. A logrithmic function is also closely related to an exponential function, which is currently only implemented as Sigmoidal Contrast Adjustment operator. This contains the same slope features you can see in the above logrithmic curves. This explains why "-sigmoidal-contrast" is a better technique for enhancing images involving low light conditions, than a Gamma Adjustment or 'power of' curve.

Sine and Cosine

As of IM v6.4.8-8 the 'sin' and 'cos' methods were added. These methods take the value given in the image and normalize it into an angle so the full range will cover a full circle of angles. The result is given a 50% bias and scaled to again fit into the normal range of values. The constant is used as a multiplier for the value (and thus the angle) so that 'N' means the function will go around the circle 'N' times over the full value range. Specifically it defines these function (using normalized values) as...

   value = 0.5 * sin( constant*value*2*PI ) + 0.5
   value = 0.5 * cos( constant*value*2*PI ) + 0.5 

In essence what these functions do is re-map the image values (usually gray-scale values) into a sine/cosine curve. For example, here I take a gradient image and modify it using these evaluate methods. Now as the constant parameter is an angle multiplier, the value given to the evaluate method will create that many peaks over the whole gradient within an image.

magick gradient.png -evaluate cos 5 -negate eval_cos_5.png

This is perfect for many tasks, from generating ripple or dispersion effects to generate ripple looking displacement curves. By using a multiplier constant of '0.5' you can simply magick a linear gradient into a sine curve gradient, which still has the same slope as the original. By negating the result you can ensure that the gradient also slopes correctly.

magick gradient.png -evaluate cos 0.5 -negate eval_cos.5.png

Which is great generating smooth gradients for use in overlapping photos. However these last two "-evaluate" methods are rarely used as they have been superseded by a more general Sinusoid Function (see below) that provide more control options, beyond that of a simple frequency option.

---

Function, Multi-Argument Evaluate

The above wave generators proved to be extremely useful, especially with Distortion Image Mapping. But it was found that a much finer control of the functions was needed, requiring more than one parameter. Because of this the "-function" operator was added in IM v6.4.8-9. Basically "-function" is a multi-argument form of "-evaluate". However unlike the Evaluate Operator, these operators like the mathematical operators, all the functions above work only on normalised channel values (0.0 to 1.0 range) of the image, which in most cases makes them easier to use.

Polynomial Function

The 'polynomial' method will take any number of values, and will modify the color values in an image according the exact expression given, much faster than the FX Operator can. Each value will be used as a coefficient from the highest order to the lowest, to produce a polynomial with the number of terms given. For example an argument of '4,-4,1' will generate the polynomial expression equivalent to the "-fx" expression " 4*u^2 - 4*u + 1 ". If you know your high school maths you should know then that this polynomial function produces a parabolic curve going from 1.0 to 0.0 then back to 1.0, over the input ('u') color range 0.0 to 1.0. That is, it will make, black and white colors 'white', and make perfect grays, 'black'.

magick gradient.png -function Polynomial 4,-4,1 func_parabola.png

You can even make a much more complex gradient, for example a quartic polynomial, which was the result of generating a Curve Level Adjustment, using a set of 'level control points'. This is typically used to adjust the colors of an image to give it various shading effects.

magick gradient.png -function Polynomial '-25, 53, -36, 8.3, 0.2' \ func_quartic.png

Of course simple linear modification is also possible, exactly as you get if you used a Level Operator...

magick gradient.png -function Polynomial '4, -1.5' func_linear.png

Note however that you can not use 'Polynomial' to do a full Threshold operation, due to the need for infinite coefficients to do so, though you can get pretty close. A single value is naturally just a constant, and results in a direct assignment of that value. In other words it is just like the "-evaluate Set " method, in this case to a 33% gray value.

magick gradient.png -function Polynomial 0.33 func_constant.png

By combining a 'Polynomial' with other math functions you can create even more complex gradient modifications. For example by taking the square root of a polynomial, I can create a true circular arc over a linear gradient. The equivalent "-fx" expression 'sqrt( -4*u^2 + 4*u + 0 )'...

magick gradient.png -function Polynomial -4,4,0 -evaluate Pow 0.5 \ func_circle_arc.png

See also the Pow Evaluate Method for an alternative to the above.

Sinusoid Function

The 'Sinusoid' function method is a much more advanced version of the "-evaluate" methods 'sin' and 'cos', and can in fact replicate those functions, but you have much better controls over how it modifies the color values in an image. And is implemented using the formula...

  value = ampl * sin(2*PI( freq*value + phase/360 ) ) + bias

This may seem complex but it ensures the function is easily to use. Only the first value 'frequency', which works exactly as per above, is required with all the other parameters being optional. By default it will generate a Sine Curve.

magick gradient.png -function Sinusoid 1 func_sine.png

By adding a 'phase' argument in degrees, you can specify the starting angle for the curve. Allowing you magick the default sine curve into a cosine.

magick gradient.png -function Sinusoid 1,90 func_cosine.png

By adjusting the 'frequency', and 'phase' I can directly magick a linear gradient into a smooth sinusoidal gradient going from black to white (minimum to maximum along a Sine curve). See Evaluate Cosine Method for a less direct method.

magick gradient.png -function Sinusoid 0.5,-90 func_sine_grad.png

The next two optional values, 'amplitude' and 'bias' controls the scale and center-line of sinusoidal curve. For example, here I make a wave (negated cosine curve) that oscillates between white and gray (values ranging from 0.75 ±0.25, or 0.5 to 1.0), starting and finishing on white.

magick gradient.png -function Sinusoid 5,90,.25,.75 func_sine_bias.png

Becareful with these last parameters as they could easy cause the waveform to exceed the bounds of the color value range, and thus be clipped (unless you are using a HDRI version of ImageMagick).

Arcsin Function

The inverse sinusoid function 'Arcsin' was added to IM v6.5.3-0. This is a special curve that was needed to generate a Cylindrical Displacement Map. It parameters are... And is implemented using the formula...

  value = range/PI * asin(2/width*( value - center ) ) + bias

By default values (if not defined) '1, 0.5, 1, 0.5' ensures the the function is centered so as to cover the whole color range from 0,0 to 1,1.

magick gradient.png -function Arcsin 1 func_arcsin.png

By halving the 'width' of the resulting curve you get...

magick gradient.png -function Arcsin 0.5 func_arcsin_width.png

The 'center' will let you reposition the curve according to the input grey values.

magick gradient.png -function Arcsin 0.4,0.7 func_arcsin_center.png

The 'range' argument allows to reduce the output range of the color values, and the 'bias' will adjust the center of that range.

magick gradient.png -function Arcsin 0.5,0.5,0.5,0.5 func_arcsin_range.png

Note how the values that are invalid as a result of the function are handled. This this allows better control when the function is used in displacements, and provides ways in which to clean them up. The actual values used are is 'bias ±range/2', as you would expect. Note that if either the 'width' or the 'range' are made negative the slope of the function will be flipped, as a result of that negative value.

magick gradient.png -function Arcsin -1 func_arcsin_neg.png

Arctan Function

The 'Arctan' method was added to IM v6.5.3-1. Its parameters are... And is implemented using the formula...

  value = range/PI * atan(slope*PI*( value - center ) ) + bias

As you can see it is almost exactly the same as the 'Arcsin' function, with only a small change to make it more useful. It even has the same set of default values (if not defined) '1, 0.5, 1.0, 0.5'. This means that if you specify a slope value of '1.0' the slope of the histogram change will produce a 1:1 change around pure gray, (no scaling) while making white and black a more gray value. For example

magick gradient.png -function Arctan 1 func_arctan.png

That is, the middle part of the gradient is actually left unchanged, with only the black and white ends becoming de-contrasted. As the 'slope' of the curve becomes larger, the gradient in the center will become stronger (more compressed in the middle), by that amount.

magick gradient.png -function Arctan 10 func_arctan_10.png

This in many ways is very similar to a Sigmoidal Contrast color modification operator. However a 'Arctan' function will NEVER actually reach the output range limits of pure black and white. It will approach those limits but never cross them. Similarly to the previous functions, (and Sigmoidal Contrast) the second argument will adjust the position of the curve relative to the input gradient values.

magick gradient.png -function Arctan 10,.7 func_arctan_center.png

And the last two arguments 'range' will let you adjust output range of values that will be generated. For example by expanding this value slightly you can ensure that it will completely cover the whole range of possible values.

magick gradient.png -function Arctan 5,0.7,1.2 func_arctan_range.png

However if you are really wanting to generate curve to modify the whole contrast of an image in this way, it is more typical to use the Sigmoidal Contrast Operator, which is designed for this purpose. The more typical use of an 'Arctan' gradient function to create a curve that will very quickly approach a specific value but not exceed that value. It is these limiting values that the 'range' and 'bias' arguments control. For example, this curve will modify the gradient in an image to produce very sharp threshold around the input gray level of 0.7, but with the values changing between the range limits of 0.5 and 1.0

magick gradient.png -function Arctan 15,0.7,0.5,0.75 func_arctan_typ.png

This is something that Sigmoidal Contrast can not generate.

---

Mathematics on Gradient Images

Now the above functions provide some very basic transformations for gradient images. But what if you want to do some mathematics with two or more gradient images. That is, modify one gradient using the gradient of another image. For this you need to use the special Mathematical Compose Methods (such as "Plus" and "Divide"). Before we start however, I would like to give you one word of warning. If your gradient images are purely grey-scale images, with no alpha channels, then you can use the Mathematical Compose Methods directly. However if you want to limit these methods to a specific channel, or apply them to the alpha (transparency) channel, then you need to ensure that you set the appropriate "-channel" setting, with no special 'Sync' channel flag. See Image Mathematics using Image Composition for more details. Normally using Mathematical Compose Methods is not really that difficult. The complications arise when you have gradients that also contain a 'bias'. That is, the gradient should represent a value of 'zero' at '50% grey, and cover a range from -1 (black) to +1 (white). Such images are often used for Distortion Image Mapping. As such performing maths on 'biased gradients' is the real problem, and what will be looked at more specifically here.

Attenuate a Biased Gradient

For example, here I want to create a sine wave, but one that starts out small, but then gets larger in amplitude. This known as 'attenuating' a biased gradient. Or putting it another way, multiply a biased gradient by another absolute gradient. It is also how 'Amplitude Modulation' such as in AM radio works! So first we need a sine wave, which we can simply generate from a linear gradient... Now to attenuate this we multiply the sine wave with a linear gradient, using a Multiply alpha composition... But to use this in say a Water Ripples, Displacement Map the wave must remain centered around a perfect gray. To do this we need to add a bias to the original image. This happened to be the same function we used to multiply the original image, negated and divided by two.... And so we have a linearly attenuated Sine Wave Gradient, suitable for use in a displacement map.

Of course you can do the whole process all in the one command, and it does not have to be a simple linear attenuation either. For example, here I attenuate the high frequency Sine wave, using a negated Cosine wave, instead of a linear gradient.

As of IM v6.5.4-3 it is now possible to do the all the steps above all in one compose method, using the special Mathematics Compose Method. Basically by recognising that an attenuation operation is the formula Sc*Dc-.5*Sc+.5 or the arguments, "1,-.5,0,.5".

magick math_sine.png math_cosine_peak.png \ -compose Mathematics -set option:compose:args 1,-.5,0,.5 \ -composite math_attenuate.png

The same result can also be achieved by first adjusting the attenuation gradient using a Polynomial Function and then using a Exclusion compose operator, to merge the images.

magick math_sine.png \( math_cosine_peak.png -function polynomial -.5,.5 \) \ -compose Exclusion -composite math_poly_excl.png

Multiply Biased Gradients

But what if BOTH functions are biased so a perfect gray means zero, and black and white represent the range from -1 to +1? Well this is a little more complex as you can't just multiply them and expect it to come out right, as the multiplication can consist of a negative values. This requires some care so as to ensure you don't end up clipping the values and getting the right negation of the curve in the resulting image. The trick is to break up the multiplication into multiple steps. That is   A × B   can also be written as   A × abs(B) × sign(B). By doing this you avoid multiplying by a negative value, which can't be stored in a normal gradient image. So all we need to do is take one of the bias gradients and separate it into two parts so they can be applied to the other gradient appropriately. The 'sign()' of a biased gradient, or getting a mask of what parts are negative, can get extracted by using a Threshold on the gradient at the bias level. You can later selectively negate the other gradient using a Composite Difference, with that threshold image. The 'abs()' of a biased gradient can be extracted easily using Solarize, then negating and doubling (using Level) that to get the absolute value of the gradient ranging from 0.0 to 1.0. As we will also need the bias offset as part of the multiply (as per Attenuate above), you can directly use the negated and half-scaled solarize output, before it is converted into the gradients absolute value. So lets magick one gradient into these three components. Now that we have these three parts of one of the gradient images, we can merge them with the other gradient. To do this we multiply by the absolute value, re-add the bias, and then negate the parts that should be made negative. And that is a perfect multiplication of two bias gradient images! Here it is again but all in the one command... One final note, unlike Attenuation, this Multiply of biased gradients is commutative. That is, swapping the input images does not effect the final result. As the above is equivelent to the formula 2*Sc*Dc-Sc-Dc+1, as of IM v6.5.4-3, you can implement the above complex steps as a single 'Mathematics' compose method using the argument "2,-1,-1,1".

magick math_sine.png math_cosine_peak.png \ -compose Mathematics -set option:compose:args 2,-1,-1,1 \ -composite math_bias_multiply.png

That is, vastly easier and faster method than the dozen or more steps needed without this argumented compose method. It so happens that once I saw that formula, I realised that this happens to be simply the negation of the 'Exclusion' compose method. Weird but true. As such the following will also generate the same zero baised multiply.

magick math_sine.png math_cosine_peak.png \ -compose exclusion -composite -negate math_excl_neg.png

Adding Biased Gradients

With the advent of the 'Mathematics' compose method, adding biased gradients is also relativally easy. The equivelent FX formula is "u+v-0.5" or a compose argument of "0,1,1,-.5". For example the following was a Fourier Transform Example that I had hand generated, requiring the addition of 3 biased sinusoids, and a constant DC value. Note in the above how I used the "-flatten" operator with a "-background" setting to implement a mutliple image composition. Or in this case a 'Biased Sum' of all the given images plus the background constant.

Frequency Modulation

By applying a function directly to the output of another function, you do NOT produce a simple result. The reason is that all these math functions are applied to the gradient 'value' of individual pixels, and not against the x value of the pixel in the gradient. For example....

magick gradient.png -evaluate sin 0.5 -normalize \ -evaluate cos 8 math_cos_var.png

This generates a very complex function that is essentually equivelent to In other words a variable frequency, where the frequency varies with the gradient of the first sine curve. Basically the faster the gradient changes in the original image, the smaller the distance between the peaks. However the height (amplitude) of the peak do not vary. This is actually how 'Frequency Modulation' works, where a seemingly simple function produces a very complex result.

---

Miscellaneous Image Transformation Techniques.

These have not been exampled yet, but are some basic IM developed transforms
that may provide useful.  If you have an interesting effect please contribute.

   pixelize an image
      resize an image down 10 then scale the image 10 to produce blocks
      of roughly averaged color.
      For example...
         magick input.jpg -resize 10% -sample 1000% output.jpg

  De-skew slightly rotated images

    -deskew {threshold}
       straighten an image. A threshold of 40% works for most images.

    Use -set option:deskew:auto-crop {width} to auto crop the image. The set
    argument is the pixel width of the image background (e.g 40).

    Programmically we auto crop by running a median filter across the image
    to eliminate salt-n-pepper noise.  Next we get the image bounds of the
    median filter image with a fuzz factor (e.g. -fuzz 5%).  Finally we
    crop the original image by the bounds.  The code looks like this:

      median_image=MedianFilterImage(image,0.0,exception);
      geometry=GetImageBoundingBox(median_image,exception);
      median_image-DestoryImage(median_image);

      print("  Auto-crop geometry: %lux%lu%+ld%+ld",
                geometry.width,geometry.height, geometry.x,geometry.y);
      crop_image=CropImage(rotate_image,&geometry,exception);

    See Trimming 'Noisy' Images

  Segmentation
    look at scripts
       divide_vert
       segment_image
    for some simple scripts I wrote to segment well defined images into
    smaller parts.   I hope to get simple segmentation functions like this
    into the core library, to allow for things like automatic sub-division of
    GIF animations, and seperating images and diagrams from scanned documents.

---