Filters - CE Image for ExpressionEngine

brightness

Changes the brightness of the image.

• arg1 - Brightness level (-255 = min brightness, 0 = no change, +255 = max brightness)

This filter seems to work as expected with images that have transparency.

filter="brightness,100"

In the example below, the first column of images has a brightness of -100, the second column does not have any filters applied, and the third column has a brightness of 100.

colorize

Like grayscale, except you can specify the color. Use arg1, arg2 and arg3 in the form of red, blue, green and arg4 for the alpha channel. The range for each color is 0 to 255.

• arg1 - Value of red component (-255 = min, 0 = no change, +255 = max)
• arg2 - Value of green component (-255 = min, 0 = no change, +255 = max)
• arg3 - Value of blue component (-255 = min, 0 = no change, +255 = max)
• arg4 - Alpha channel, A value between 0 and 127. 0 indicates completely opaque while 127 indicates completely transparent. This parameter was added in PHP version 5.2.5

This filter seems to work as expected with images that have transparency.

filter="colorize,255,0,0,0"

The image columns below show manipulation of the red, green, and blue color components respectively.

contrast

Changes the contrast of the image. Use arg1 to set the level of contrast.

• arg1 - Contrast level (-100 = max contrast, 0 = no change, +100 = min contrast (note the direction!))

This filter seems to work as expected with images that have transparency.

filter="contrast,50"

In the example below, the first column of images has a contrast of -50, the second column does not have any filters applied, and the third column has a contrast of 50.

edgedetect

Uses edge detection to highlight the edges in the image.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="edgedetect"

In the example below, the first column of images employs the edgedetect filter by itself, the second column has both edgedetect and grayscale filters applied, and the third column shows the images without any filters.

emboss

Embosses the image.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="emboss"

In the example below, the first column of images employs the emboss filter by itself, the second column has both emboss and grayscale filters applied, and the third column shows the images without any filters.

emboss_color

Embosses the image, preserving the image’s color.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="emboss_color"

In the example below, the first column of images shows the emboss_color filter, the second column shows the images with the traditional emboss filter applied, and the third column shows the images without any filters.

gaussian_blur

Blurs the image using the Gaussian method.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="gaussian_blur"

In the below example, the first column of images has the guassian_blur filter applied, the second has the filter applied with a background image specified (notice the favorable difference in the png image), and the final column represents the images without any filters.

grayscale

Converts the image to grayscale. This filter seems to work as expected with images that have transparency.

filter="grayscale"

In the below example, the first column of images has the grayscale filter applied, and the second column represents the images without any filters.

mean_removal

Uses mean removal to achieve a "sketchy" effect.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="mean_removal"

In the below example, the first column of images has the mean_removal filter applied, the second column has the filter applied and specifies a background color (notice the favorable difference in the logo), and the third column represents the images without any filters.

negate

Reverses all colors of the image. This filter seems to work as expected with images that have transparency.

filter="negate"

In the below example, the first column of images has the negate filter applied, and the second column represents the images without any filters.

opacity

Sets the opacity of an image. If the image is opaque, it fakes the opacity by blending it with the background color. Use arg1 to set the opacity level.

• arg1 - The opacity level - 0 (transparent) to 100 (opaque)

filter="opacity,10"

pixelate

Applies a pixelation effect to the image. Use arg1 to set the block size and arg2 to set the pixelation effect mode.

• arg1 - Block size in pixels
• arg2 - Whether to use an advanced (more accurate) pixelation effect or not (defaults to FALSE).

Note: If you are using a version of PHP before 5.3.0, or you are running the Ubuntu GD library, the pixelate filter will not work. Don’t despair, as a custom pixelate filter is included with CE Image. To use the custom pixelate filter, simply prepend an underscore to the filter name (filter="_pixelate").

Unlike the native filter, the custom filter will always use an exact pixelation effect. Additionally, the custom filter supports transparency better than the native filter. You can elect to use the custom filter (even if you have support for the native filter) by simply prepending an underscore to the filter name (filter="_pixelate").

This filter seems to work as expected with images that have transparency.

filter="pixelate,10,TRUE"

In the below example, the first column of images has the pixelate filter applied with a block size of 10px and the advanced pixelation effect enabled, and the second column represents the images without any filters.

replace_colors

Allows you to replace a color (or color range), with a color or transparency. The arguments are in the form of color,replacement[,color,replacement...etc]

• argOdd - color - A color hexadecimal value (ie, #fff) or a color range (ie, #fff-#f00)
• argEven - replacement - A color hexidecimal value (ie, #fff). Leave empty to replace with transparency.
• The above arguments may be repeated.

filter="replace_colors,#fffffe-#ccc,"

selective_blur

Blurs the image.

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="selective_blur"

In the below example, the first column of images has the selective_blur filter applied, the second has the filter applied and specifies a background color (notice the difference in the appearance of the logo), and the third column represents the images without any filters.

sepia

Applies a sepia tone filter to the image.

filter="sepia"

sharpen

This filter sharpens the image using Torstein Hønsi’s excellent unsharp mask PHP script. When images are resized by PHP, they often appear a bit blurry. You can use this filter to sharpen the images to your taste. Use arg1, arg2, and arg3 in the form of amount, radius, and threshold:

• arg1 - Amount - How much of the effect you want, 100 is 'normal.' (typically 50 to 200, defaults to 80)
• arg2 - Radius - Radius of the blurring circle of the mask. (typically 0.5 to 1, defaults to .5)
• arg3 - Threshold - The least difference in color values that is allowed between the original and the mask. In practice this means that low-contrast areas of the picture are left unrendered whereas edges are treated normally. This is good for pictures of e.g. skin or blue skies. (typically 0 to 5, defaults to 3)

This filter works alright with images that have transparency, but seems to look a little better when a background color is chosen.

Note: This filter can be process intensive (especially with versions of PHP before 5.1). However, as with the other filters, this should only be an issue if the image is not already cached.

filter="sharpen"

In the below example, the first column of images has the sharpen filter applied with the default settings (which is the same as specifying filter="sharpen,80,.5,3"), the second has the amount sub parameter doubled in value and designates a background color (notice the favorable difference in the png image), and the last column represents the images without any filters.

smooth

Makes the image smoother. Use arg1 to set the level of smoothness.

• arg1 - Smoothness level (Applies a 9-cell convolution matrix where center pixel has the weight arg1 and others weight of 1.0. The result is normalized by dividing the sum with arg1 + 8.0 (sum of the matrix). any float is accepted, large value (in practice: 2048 or more) = no change)

Note: Transparency may be lost when using this filter (see filter transparency for more info).

filter="smooth,100"

In the below example, the first column of images has the smooth filter applied with a smoothness level of 1, the second is the same as the first but with the addition of a background color (notice the favorable difference in the png image), and the last column represents the images without any filters.

sobel_edgify

This is an edge detection filter that uses the sobel technique. This filter is very slow (but this will not be an issue after it is run the first time because it will be cached), so be cautious applying it to large images.

• arg1 - Threshold - Lower thresholds will show more lines. (0 to 255, defaults to 40)
• arg2 - Foreground Color - Hexadecimal color value (3 or 6 digits) or ''(transparent). Defaults to ''(transparent).

This filter works alright with images that have transparency, but seems to look a little better when a background color is chosen. If no background color is specified using the bg_color parameter, the background will be transparent if a png, and will default to 'ffffff' (white) if a jpg or gif. If no foreground color is specified via arg2, the foreground color will be transparent if a png and black otherwise.

Note: If you do not specify a foreground color (arg2), and do not specify a background color via the bg_color parameter, you may get a completely blank image.

Note: This filter can be process intensive (especially with versions of PHP before 5.1). However, as with the other filters, this should only be an issue if the image is not already cached.

filter="sobel_edgify"

In the below example, the first column of images has the sobel_edgify filter applied with a threshold of 40 and the f6861f foreground color with a transparent background, the second has the threshold sub parameter set to 60 in value and designates a background color with a transparent foreground, and the last column represents the images without any filters.

How To Apply Multiple Filters Simultaneously

Filters can also be stacked to create cool effects! In the example below, the first column of images has two filters (grayscale and negate) applied to achieve an “x-ray” effect, the second column of images has two filters applied (pixelate, sobel_edgify), and the third column represents the images without filters.

If A Filter Does Not Work

If you pass in a filter and it does not work, your version of PHP probably does not support that filter. All filters require PHP 5+, the colorize filter needs version 5.2.5 for the last argument to work (alpha level), and the pixelate filter was added as of PHP 5.3.0.

If Background Transparency Is Lost When Using Filters

Do the image alpha channels turn black or dark gray when applying filters? This can sometimes happen when applying filters to png images, depending on your PHP version and configuration. Background transparency seems to work well when using PHP versions 5.2.11 and newer.

We have tried to document which filters seem to be problematic with transparency on PHP versions before 5.2.11. In particular, these filters can sometimes cause the alpha channel to be lost: edgedetect, emboss, gaussian_blur, mean_removal, selective_blur (not completely black, just some weird artifacts around edges), and smooth. Setting the background color to be the same color as your html background color may be a work around for the following filters: gaussian_blur, mean_removal, selective_blur, and smooth.

All of the image filters should still work on images with no transparency (assuming you have the appropriate version of PHP installed for the respective filter).

Where To Learn More

See http://php.net/manual/en/function.imagefilter.php for more details on PHP image filters.