Add-on Documentation from JCOGS Design

FiltersLast updated: 11 March 2022

auto_sharpen

CE Image Compatibility: Full

A filter that sharpens an image that has been reduced in size (e.g. via resize): the amount of sharpening is set automatically depending on the manipulated image’s width compared to its original width. If the manipulated image is larger than the original image, this filter is ignored.

This filter uses a variable Laplacian filter broadly similar to the one used by, and the variable sharpening effect has been calibrated to give similar results to, the equivalent CE Image filter.

For increased control over the sharpening applied, consider using the sharpen filter instead.

Syntax + Examples

filter='auto_sharpen'

filter='auto_sharpen'

Illustration

{exp:jcogs_img:image width='300'}

Image resized, no filter applied

Illustration

{exp:jcogs_img:image width='300' filter='auto_sharpen'}

Auto-sharpen applied to a regular sized image

Illustration

{exp:jcogs_img:image width='100' filter='auto_sharpen'}

Auto-sharpen applied to a small image

brightness

CE Image Compatibility: Full

Adjusts the brightness of the image. Takes one value - an integer in range -255 to +255. A value of 0 produces no change, positive numbers increase brightness. Default = 0.

Syntax + Examples

filter="brightness,<integer>" - default integer value: 0

filter="brightness,30"

Illustration

{exp:jcogs_img:image width='300' filter='brightness,40'}

In this example the image is brightened by 40/255 of the maximum brightness adjustment (i.e. increased by 15%).

Illustration

{exp:jcogs_img:image width='300' filter='brightness,-40'}

In this example the image is darkened by 40/255 of the maximum brightness adjustment (i.e. decreased by 15%).

blur

CE Image Compatibility: New feature

Applies a gaussian blur filter to the current image. One value adjusts the amount of blur applied: value an integer in range 0 to +100. A value of 0 produces no change, positive numbers increase amount of blur. Default = 1.

Syntax + Examples

filter="blur,<integer>" - default integer value: 0

filter="blur,30"

Illustration

{exp:jcogs_img:image width='300' filter='gaussian_blur,30'}

Increase the blur in the source image by 30/100 of total range.

Usage Notes

The way in which the amount of blur applied to an image is calculated in a different way to that used in CE Image. So if you are updating a site that previously used CE Image, to get the same blur effect the value of blur applied may need to be adjusted.

colorize

CE Image Compatibility: Full

Adjusts the Red, Green and Blue components of an image. Three parameters, each a value in range -255 to +255. A value of 0 produces no change, positive numbers increase strength of colour. Default = 0.

Syntax + Examples

filter="colorize,<integer>,<integer>,<integer>" - default integer value: 0,0,0

filter='colorize,-20,20,-20'

Illustration

{exp:jcogs_img:image width='300' filter='colorize,-20,20,-20'}

This filter reduces the strength of the Red and Blue channels each by 20/255 (8%), and increases the stength of the Green channel by 20/255 (8%).

contrast

CE Image Compatibility: Full

Adjusts the contrast of the image. One parameter, a value in range -100 to +100. A value of 0 produces no change, positive numbers decrease contrast. Default = 0.

Syntax + Examples

filter="contrast,<integer>" - default integer value: 0

filter="contrast,30"

Illustration

{exp:jcogs_img:image width='300' filter='contrast,-40'}

In this example the image contrast is increased by 40/100 (40%) of the maximum adjustment, by specifying a negative amount of contrast (-40).

Usage Notes

The CE Image version of this filter has a peculiar scaling system for filter values - with maximum contrast being generated when the filter is set to its most negative value -100.

For compatibility purposes JCOGS Image has adopted this scaling system, but we are first to say that we simply have no idea why it is the way it is…!

dominant_color

Generate a colour field image the same size as the source image, coloured with the ‘dominant colour' of the source image.

The ‘dominant color’ of an image is the most prevalent colour in an image. Working out which colour is dominant is a complicated process, JCOGS Image uses the well regarded Modified Median Cut Quantization method.

Syntax

filter='dominant_color'

Illustration

{exp:jcogs_img:image width='300' filter='dominant_color'}

Create a colour field the same size as source image, coloured with the dominant colour of the source image.

edgedetect

CE Image Compatibility: Full

Uses edge detection to highlight the edges in the image.

Syntax + Examples

filter="edgedetect"

filter="edgedetect"

Illustration

{exp:jcogs_img:image width='300' filter='edgedetect'}

Apply edgedetect filter to an image.

Usage Notes

This filter is one of a set of standard php filters.

emboss

CE Image Compatibility: Full

Applies an emboss filter to the current image. No parameters.

Syntax + Examples

filter="emboss"

filter="emboss"

Illustration

{exp:jcogs_img:image width='300' filter='emboss'}

Apply the emboss filter.

Illustration

{exp:jcogs_img:image width='300' filter='emboss|grayscale'}

Apply the emboss filter followed by the greyscale filter.

Usage Notes

The emboss filter sometimes generates colour artifacts on the image. A simple way to remove them is to apply the greyscale filter after the emboss filter. See second example above.

Usage Notes

This filter is one of a set of standard php filters.

gaussian_blur

CE Image Compatibility: Partial

This parameter is an alias of the JCOGS Image blur filter and included for upgrade compatibility.

Please note the comments on equivalence between JCOGS Image blur and CE Image gaussian_blur provided in the entry for JCOGS Image blur filter.

grayscale

CE Image Compatibility: Full

Converts an image to a greyscale version. No parameters.

Syntax + Examples

filter="grayscale"

filter="grayscale"

Illustration

{exp:jcogs_img:image width='300' filter='grayscale'}

Create a greyscale copy of the source image.

greyscale

CE Image Compatibility: New feature

An alias of the JCOGS Image grayscale filter, included to placate British English speaking users of the add-on… 

Syntax + Examples

filter="greyscale"

filter="greyscale"

invert

CE Image Compatibility: New feature

Reverses all colors of the current image to create a “negative” version of the source image. No parameters.

Syntax + Examples

filter="invert"

filter="invert"

Illustration

{exp:jcogs_img:image width='300' filter='invert'}

Create an inverted copy of the source image.

lqip

CE Image Compatibility: New feature

Generate a ‘low quality image placeholder’ version of the processed image.

LQIP images are generated by applying the pixelate and blur filters to an image, and then saving it at 50% quality.  Typically the file-size of these images is between 25% and 16% of the size of the unfiltered processed image.

Syntax

filter="lqip"

Illustration

{exp:jcogs_img:image width='300' filter='lqip'}

Generate an LQIP version of the source image

mask

CE Image Compatibility: New feature

Apply a mask to a processed image.

The mask can either be a standard shape or an image that you have created for the purpose.

Image Masks

Create an image with a white background where the area you wish to be used as a mask is coloured black. The mask can be any dimensions, but note that the image will be scaled horizontally and vertically to fit into bounding box for processed image.

Shape Masks

Choose from circle, ellipse, polygon or star shapes.

Circle

Specify the horizontal and vertical location within the processed image bounding box for the center of the circle to be placed and its diameter using any of the valid JCOGS Image dimension forms (integer, px, %). If you specify a percentage, it will be calculated with reference to the bounding box's minor axis length - so a size of 100% will always just fit within the image box regardless of orientation. 

Ellipse

Specify the location within the processed image bounding box for the center of the ellipse to be placed and its horizontal and vertical widths using any of the valid JCOGS Image dimension forms (integer, px, %). If you specify a percentage, it will be calculated with reference to the bounding box's minor axis length - so a size of 100% will always just fit within the image box regardless of orientation. 

Polygon

Specify the number of sides you wish the regular polygon to have by appending this number to the name: so polygon-7 will generate a regular polygon with seven sides. Use the remaining parameters to specify the horizontal and vertical location within the processed image bounding box for the center of the polygon and the width of the polygon using any of the valid JCOGS Image dimension forms (integer, px, %). In the final parameter you can specify a rotation (an integer number of degrees rotation) for the shape - positive numbers give clockwise rotations, negative anti-clockwise.

Star

Specify the number of points you wish the regular star to have by appending this number to the name: so star-5 will generate a regular star with seven spikes. Use the remaining parameters to specify the horizontal and vertical location within the processed image bounding box for the center of the star and the width of the polygon using any of the valid JCOGS Image dimension forms (integer, px, %). You can also specify a rotation (an integer number of degrees rotation) for the shape - positive numbers give clockwise rotations, negative anti-clockwise - and the ratio between the width of the star's inner core and the star as a whole (determines how ‘long’ the spikes will be) - the ratio value should be a number between 0 and 1.

Syntax

filter="mask,image,<image path>"

filter="mask,circle|ellipse|polygon-x|star-x,<horizontal position>,<vertical position>,<width>[<ellipse height>|<rotation>[|,<star-split>]]

filter="mask, media/images/mask_image.png"

filter="mask, circle, 20%, 40%, 70%"

filter="mask, ellipse, 50%, 50%, 60%, 40%"

filter="mask, polygon-5, 50%, 50%, 100%, 20"

filter="mask, star-7, 50%, 50%, 100%, 15, 0.75" 

Illustration

{exp:jcogs_img:image width='300' filter='mask,image,/media/squiggle.png'}
Image Mask Used

Create a masked version of processed image, where mask is based on an image file.

Illustration

{exp:jcogs_img:image width='300' filter='mask, circle, 50%, 50%, 85%'}

Create a masked version of processed image, where mask is a circle centered on image with width 85% of image minor width.

Illustration

{exp:jcogs_img:image width='300' filter='mask, circle, -20%, 50%, 200%'}

Create a masked version of processed image, where mask is a circle centered 20% off to left of image and on the centreline of the image, with a width equal to 200% of image minor width.

Illustration

{exp:jcogs_img:image width='300' filter='mask, ellipse, 50%, 50%, 85%, 55%'}

Create a masked version of processed image, where mask is an ellipse centered on image with width 85% of image minor width and height 55% of image minor width.

Illustration

{exp:jcogs_img:image width='300' filter='mask, polygon-5, 50%, 50%, 85%, 20'}

Create a masked version of processed image, where mask is a pentagon (5 sided regular polygon) centered on image with width 85% of image minor width, rotated clockwise by 20°.

Polygons must have a minimum of 3 sides.

Illustration

{exp:jcogs_img:image width='300' filter='mask, star-9, 50%, 50%, 85%, 15, 0.65'}

Create a masked version of processed image, where mask is a 9 pointed star centered on image with width 85% of image minor width, rotated clockwise by 15°, with the star central area being 0.65 of calculated width of star.

Stars must have a minimum of 3 points.

Illustration

{exp:jcogs_img:image width='300' filter='mask, star-13, 50%, 50%, 100%, 15, 0.85' bg_color='#a74e87' save_type='jpg'}

Create a masked version of processed image, where mask is a 8 pointed star centered on image with width 85% of image minor width, rotated clockwise by 15°, with the star central area being 0.85 of calculated width of star.

Image saved as a jpg (no transparency) so background colour used to fill background.

Stars must have a minimum of 3 points.

Usage Notes

Although any valid JCOGS Image dimension can be used to specify the dimensions of the generated shapes, it is strongly recommended that you use percentage values to specify dimensions.

Usage Notes

The position and size of generated shapes (circle, ellipse, polygon, star) can be set to be outside or larger than processed image, when this happens the mask shape will be calculated and only the overlap between the mask shape and the image used to generate the masked image.

Usage Notes

If you apply a mask to an image and save it using  a format that supports transparency, the background behind the masked image will transparent. If you apply a mask to an image and save it using a format that does not support transparency, the background behind the masked image will be set to the specified background colour (either via parameter in the tag, or the default background colour).

mean_removal

CE Image Compatibility: Full

Uses mean removal to achieve a "sketchy" effect.

Syntax + Examples

filter="mean_removal"

filter="mean_removal"

Illustration

{exp:jcogs_img:image width='300' filter='mean_removal'}

Apply the mean removal filter to an image.

Usage Notes

This filter is one of a set of standard php filters.

negate

CE Image Compatibility: Full

An alias of the JCOGS Image filter invert. Included for CE Image filter parameter compatibility.

Syntax + Examples

filter="negate"

filter="negate"

opacity

CE Image Compatibility: Full

Set the opacity in percent of the current image ranging from 100% for opaque and 0% for full transparency. One parameter, a value in range 0 to +100. A value of 100 produces no change. Default = 100.

Syntax + Examples

filter="opacity,<integer>" - Default: 100

filter="opacity,70"

Illustration

{exp:jcogs_img:image width='300' filter='opacity,50'}

Reduce image opacity to 50% of source image level.

Usage Notes

Opacity can be changed on any image but can only be usefully saved in a format that supports transparency - for now that limits use of this filter to source images using the PNG format (support for WEBP transparency is to be supported in a future update).

pixelate

CE Image Compatibility: Full

Applies a pixelation effect to the current image. One value, the size of the pixel block to use for the pixelation effect. A value of 0 produces no change. Default = 0.

Syntax + Examples

filter="pixelate,<integer>" - Default: 0

filter="pixelate,10"

Illustration

{exp:jcogs_img:image width='300' filter='pixelate,12'}

Add pixelation to source image using a 12x12 pixel block.

scatter

Applies scatter effect to the image, use <strong>arg1</strong> and <strong>arg2</strong> to define the effect strength.  <strong>arg2</strong> must always be greater than <strong>arg1</strong>

The default value for arg1 is 3.

If arg2 is not set, its default value is twice the value of arg1.

If arg1 is set to a value greater than arg2 it is reset to a value equal to half of arg2.

Syntax + Examples

filter="scatter[,<arg1 integer>[,<arg2 integer>]]" - default value arg1: 3, default value arg2: 4

filter="scatter"

filter="scatter,6"

filter="scatter,8,15"

Illustration

{exp:jcogs_img:image width='300' filter='scatter'}

Apply basic scatter filter (i.e. default values for arg1 of 3, arg2 of 6)

Illustration

{exp:jcogs_img:image width='300' filter='scatter,10'}

Apply scatter filter with arg1 set to 10 (i.e. default value for arg2 of 20)

Illustration

{exp:jcogs_img:image width='300' filter='scatter,10,12'}

Apply scatter filter with arg1 set to 10, arg2 set to 12.

Usage Notes

This filter is one of a set of standard php filters. It introduces some image artifacts for higher values of the arg1 and arg2 parameters (in the examples you can see these along bottom edge of images).

selective_blur

CE Image Compatibility: Full

Applies a simple blur method to an image. To increase the effect apply the filter multiple times by specifying a repeat count (default 1).

Syntax + Examples

filter="selective_blur[,<integer>]" - default integer value: 1

filter="selective_blur"

filter="selective_blur,4"

Illustration

{exp:jcogs_img:image width='300' filter='selective_blur'}

Apply the selective blur filter one time.

Illustration

{exp:jcogs_img:image width='300' filter='selective_blur,5'}

Apply the selective_blur filter five times

Usage Notes

This filter is one of a set of standard php filters.

sepia

CE Image Compatibility: Full

The sepia filter applies a treatment to digital images to make them take on the appearance of traditional sepia toned photographic images.

It has just one sub-parameter, the option to choose between two methods of rendering the sepia effect:

  • fast - A simple approach that gives a good approximation of sepia toning and (as its name suggests) is fast in operation;
  • slow - A more complex approach that gives a higher contrast / higher quality sepia image but takes longer to process.

The default option is fast.

The slow option uses a similar approach to the sepia filter used by CE Image (which uses a method that appears to be based on the code examples on this page).

Syntax + Examples

filter="sepia[,fast|slow]" - default value: fast

filter="sepia"

filter="sepia,fast"

filter="sepia,slow"

Illustration

{exp:jcogs_img:image width='300' filter='sepia'}

The ‘fast’ sepia filter applied to an image.

Illustration

{exp:jcogs_img:image width='300' filter='sepia,slow'}

The ‘slow’ sepia filter applied to an image.

Usage Notes

Sepia is the name of a brown ink colour popular in historical times. It is also the name given to the colouration given to some photographic images as a result of a chemical process designed to help them remain stable for longer which gave monochrome images a brown cast. In more recent times it has become a familiar colour adjustment for digital pictures.

Usage Notes

Caution: the ‘slow’ version of the filter uses a processor intensive method to determine the image transformation required to render the sepia version of the image: the processing time using the slow version is about 5x longer than using the fast version. For small (dimension) images this difference may not be noticeable, for large (dimension) images use of the slow version may cause significant issues on some servers.

sharpen

CE Image Compatibility: Full

Sharpens current image using an unsharp mask filter.

The filter can be given three sub-parameters, all of which are optional:

  • amount - a number giving an indication of ‘how much’ sharpening you want to apply. The possible range is 0 → 500. The default value is 80. The bigger the number the stronger the sharpening effect;
  • radius - controls the amount of blurring to apply to image during the sharpening process (see usage notes for more on this). The possible range is 0 → 50, typical useful values are in the range 0.5 → 1. The default value is 0.5. With bigger values some edges in the image may be a bit sharper - but in practice this value doesn't change things much.
  • threshold - controls the degree to which the sharpening emphasises the edges in your image. The possible range is 0 → 255, typical useful values are in the range 0 → 5. The default value is 3. The bigger the value, the less clearly defined are the ‘edges’ in the image.

Syntax + Examples

filter="sharpen[,<amount>[,<radius>[,<threshold>]]]" - Default: amount - 80, radius - 0.5, threshold - 3

filter="sharpen"

filter="sharpen,120"

filter="sharpen,120,5,10"

Illustration

{exp:jcogs_img:image width='300' filter='sharpen'}

Increase the sharpness of the image by the default amount

Illustration

{exp:jcogs_img:image width='300' filter='sharpen,160'}

Increase the sharpness of the image by twice the default amount

Usage Notes

Unsharp masking is a traditional darkroom technique that has proven very suitable for digital imaging; it is particularly useful for ‘de-blurring’ images that have been resized (e.g. to make thumbnails) as it tends to highlight edges while low-contrast areas of the picture are left largely unaffected.

The principle of unsharp masking is to create a blurred copy of the image and compare it to the underlying original. The difference in colour values between the two images is greatest for the pixels near sharp edges. When this difference is subtracted from the original image, the edges will be accentuated.

smooth

CE Image Compatibility: Full

Apply a smoothing filter to the image. Use variable to adjust amount of smoothing applied (default value 1)

Syntax + Examples

filter="smooth[,<integer>]" - default integer value: 1

filter="smooth"

filter="smooth, 10"

Illustration

{exp:jcogs_img:image width='300' filter='smooth'}

Apply default smoothing to an image.

Illustration

{exp:jcogs_img:image width='300' filter='smooth,10'}

Apply extra smoothing to an image (value 10)

Usage Notes

This filter is one of a set of standard php filters.

sobel_edgify

CE Image Compatibility: Partial

A filter that highlights edges using a method called the sobel operator

The filter has only one sub-parameter - threshold - which controls how aggressive the filter is about identifying edges - the higher the number the more extreme the algorithm; in practical terms the higher the number the fewer edges will be returned in the processed image. Due to differences in the way the filter is calculated the threshold values are not directly equivalent to those used in CE Image: the filter has been calibrated to give similar results under default conditions (i.e. with no threshold value set) but if you are setting the threshold value yourself you will find that the threshold value used for JCOGS Image will need to be about 3x the size you would use in CE Image (so if you would use 50 in CE Image, try 150 in JCOGS Image).

Syntax + Examples

filter='sobel_edgify[,<threshold>] - default value: threshold = 125

filter='sobel_edgify'

filter='sobel_edgify, 200'

Illustration

{exp:jcogs_img:image width='300' filter='sobel_edgify'}

Sobel Edgify Filter applied with default settings.

Illustration

{exp:jcogs_img:image width='300' filter='sobel_edgify, 200'}

Sobel Edgify Filter applied with threshold of 200

Usage Notes

The Edgify filter is relatively processor intensive to apply - it takes about 4x longer to process a typical image than something like the auto_sharpen filter, so it makes sense to turn on caching when you plan to use it extensively.