ParametersLast updated: 17 August 2023

A parameter that requests JCOGS Image to apply the auto_sharpen filter to the processed image. 

There is only one valued - either yes or no - if the value is yes then the auto_sharpen filter is applied to the image during processing. 

This parameter is equivalent to including the term ‘auto_sharpen’ in the string supplied to the filter parameter. The parameter is primarily intended as a means to give users the ability to selectively over-write the setting of the Enable Auto Sharpening by default default image setting.

Note: if the filter parameter is supplied the ‘auto_sharpen’ value, the filter will be applied to the processed image regardless of the value provided by the auto_sharpen parameter.

Illustration

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

Apply the sharpen filter to an image using the auto_sharpen parameter.

Determines whether  HTML img dimension parameters width= and height= will be included within <img> tag.  The parameter is ignored where the tag does not output an <img> tag.

Illustration

{exp:jcogs_img:image add_dims="yes" width="300"}

This single JCOGS Image tag will produce an HTML img tag containing width= and height= parameters.

An alias for the add_dims parameter. See the definition of add_dims for parameters.

This parameter controls whether JCOGS Image is allowed to increase the size of the image to fit within the dimensions specified for the final image.

Adds a constraint to some operations to use the specified aspect ratio to constrain the dimensions of the final image. 

The aspect ratio is defined as the ratio between the horizontal and vertical dimensions, and is submitted to the addon in the form of two values separated by a spacing character - for example 16_9.  The first integer value relates to the horizontal dimension, and the second to the vertical dimension. Any two values can be used. 

If the value given does not conform to the required format, the aspect ratio parameter is ignored.

If both width and height are specified in the tag then this parameter is ignored.

Most often the parameter is used with the crop operation, but also can be used when resizing images and the fit parameter is specified.

For cropping operations, aspect ratio is used to calculate the required image height if only width is specified, or the required image width if only height is specified. If neither width nor height are specified, the required height is calculated based on the width of the source image.

For resizing operations where only one dimension is specified (height or width) the aspect ratio is used to impute the other dimension of the ‘bounding box’ for the resized image so that the fit parameter can determine the appropriate height and width for the image after the resize.

Illustration

{exp:jcogs_img:image width='300' aspect_ratio='16_9' crop='y'}

In this example the image will be scaled to be 300 px wide, and the height is set according to the aspect ratio specified.

Any content within an attributes= tag is passed through to the tag output unchanged.

If creation of an <img> tag is requested this content is simply placed within the tag along with any calculated values (e.g. width). 

The content is also available via the {attributes} variable which can be used in a single JCOGS Image tag within the output= parameter, or when using a tag-pair.

Note: The parameter is included primarily for compatibilty reasons with CE Image - JCOGS Image's “pass-through” behaviour means that any parameters that are found within the Image tag and are not recognised as “Image” tags are automatically passed through to the output: the only time attributes= is useful is when you specifically want to pass through a parameter that would otherwise be interpreted / acted upon by Image.

Illustration

{exp:jcogs_img:image width='300' attributes="class='cats'" class="dogs"}

This example adds the content class='cats dogs' to the HTML <img> tag created by combining the class value specified in the attributes= parameter with the class attribute passed through as an unrecognised parameter.

Defines the colour of the background behind the image layer during processing. If the image processing (e.g. rotation or the removal of transparency) will cause the background to show, this is the colour that appears.

The colour can be specified using any valid JCOGS Image colour format.

Define a solid color border around an image. 

For operations that change the shape of the image - for example applying a shape mask or rounded corners - the border is drawn relative to the resulting shape.

The border width can be be specified using any valid JCOGS Image dimension format (i.e. with or without a px suffix or as a %). % values will be evaluated relative to the width of the processed image that the border is being added to.

The colour should be specified using any valid JCOGS Image Colour format.

Illustration

{exp:jcogs_img:image width='300' border='10|4a2d14'}

In this illustration a border colour #4a2d14 that is 10 pixels wide is added to the image.

Illustration

{exp:jcogs_img:image width='300' border='15px|rgb(220,240,260)' rounded_corners='all,20px' save_type='png'}

A border added to an image with rounded corners.

Illustration

{exp:jcogs_img:image width='300' border='15px|rgb(255,176,5)' filter='mask,polygon-7' save_type='png'}

A border added to an image that has been masked with a shape.

This parameter allows the cache setting for an image to be set at the tag level.

The parameter takes one value, which indicates the duration that cached image should remain in the cache.  There are three options:

• cache="-1" The cache is set to ‘perpetual’ mode - an image will be kept in the cache until it is deleted (or overwritten). This option is the default value set when JCOGS Image is first installed.
• cache="0" The cache is disabled - processed images will not be saved to the cache, and JCOGS Image will not look for cached copies of processed images.
• cache="<integer>" JCOGS Image will create cache copies of processed images and continue to use them for <integer> seconds after the cached image is created.

If set in a tag, the value will over-rule the default value set in the JCOGS Image Control Panel Settings area (which is set to -1 when JCOGS Image is first installed).

Defines the path to the JCOGS Image cache folder relative to the web_root directory.

This value if specified in a tag will over-rule the default location specified in the JCOGS Image control panel settings for that tag only.

JCOGS Image's powerful cache management tools will recognise where an image is saved to a location outside of the default cache location and will monitor the image's cache status.

By default, Image provides an advanced class / style consolidation feature for by the tag-pair and bulk-tag operating modes - to ensure that your output contains just one instance each of class and style attributes.

For some complex cases, this class / style consolidation feature can cause problems, so this tag based control allows you to disable it on a case by case basis.

Controls whether a tag will produce as output an HTML <img> tag.

The default for single tags is for create_tag= to be ‘yes’, the default for tag-pairs is for create_tag= to be ‘no’; this difference reflects the different modes of operation provided by single and pair tags.

Controls whether an image will be resized to fit the dimensions given (the default behaviour) or will be cropped. 

To enable cropping rather than resizing, simply add the parameter crop="yes" to your JCOGS Image tag - this will request JCOGS Image to crop your image using its default options for crop.

There are a large number of options for controlling how a crop is made, and if you want a different crop to the default one provided by crop="yes" read on… 

How cropping works

Cropping an image replaces the source image with a smaller section of image; you can control the size of the smaller section and also its position on the source picture.

Controlling crop

Size

The size of the cropped portion of the source image will be determined by dimensions given in your tag: these can be specified either by specifying both width and height parameters (or their proxies, such as min-height or max); alternatively image can calculate these values if you specify one dimension and give an aspect ratio. 

If smart scaling is enabled (the default) the image will be resized to ensure that the smaller of the source image's dimensions matches the equivalent dimension specified for the processed image - with the larger dimension being cropped to the match the other dimension specified for the processed image.

Note: If you do not supply enough information for Image to be able to work out both dimensions of the crop, Image will abandon the crop and leave the image unchanged. 

Position

The position of the smaller section of the image relative to the source image is determined by the four optional values that can be associated with this parameter. Each optional value is separated from the others by the | symbol.

1. The first value indicates whether or not to crop the image and takes the values yes, no, or face_detect.  
   • The default value is no. If the first value is not either yes or face_detect then the tag and its content is ignored during Image processing.
   • If the value yes is given, Image will attempt to crop the image according to the dimension information provided in the tag, and / or using smart scaling.
   • If face_detect is selected Image will first attempt to find faces within the image; if it finds any faces it will adjust the crop to focus on the faces found and any other crop parameters set will be ignored. Focusing on faces found means that the crop dimensions and location will be set to match the bounding box of the face(s) found plus the width of the parameter face_crop_margin if it is specified (default value of which is 0). If no faces are found, choosing face_detect is equivalent to choosing yes and the image will be cropped based on the dimension information given in the tag.
2. The second value specifies the overall position for the crop relative to the source image in the form horizontal location, vertical location; where the horizontal position is one of left, center, right, or face_detect and the vertical position is one of bottom, center, top, or face_detect. 
   • Setting either the horizontal or vertical locations to face_detect will instruct JCOGS Image to position the crop such that, for the direction specified, the centre of the crop will be aligned with the centre of any group of faces detected within the image. If no faces are detected, the crop will position will fallback to the default of center.
3. The third value specifies an adjustment of the position for the crop relative to the overall position specified in optional value 2, and is defined by two values, the first specifying how much to move the crop shape horizontally the second how much to move the crop shape vertically. The values can be positive or negative integers, and specified in any of the valid JCOGS Image Dimension formats. The default values are 0,0.
4. The fourth value specifies whether to use smart scaling. It can take the values yes or no. The default value is yes.

Because of these defaults, specifying crop='yes' in a tag is sufficient to cause it be cropped relative to the center point of the source image, and for the cropped image to be adjusted via super scaling.

Illustration

{exp:jcogs_img:image width='300' height='200' crop='yes'}

Crop an image to be 300 pixels wide and 200 pixles tall.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 200px

Illustration

{exp:jcogs_img:image width='300' crop='yes' aspect_ratio='7:5'}

Crop an image to be 300 pixels wide and with an aspect ratio of 7x5.

The resulting image is smart scaled to fit into a shape with dimensions 300px by 214px

Illustration

{exp:jcogs_img:image width='200' crop='yes|||no' aspect_ratio='5:7'}

Crop an image to be 200 pixels wide with an aspect ratio of 5x7 with smart scaling turned off.

The resulting image will be a sub-section of the center of the image with dimensions 200px x 280px.

Illustration

{exp:jcogs_img:image width='300' crop='yes|left,top|100,100|no' aspect_ratio='16_9'}

Crop an image to be 300 pixels wide with an aspect ratio of 16:9 with smart scaling turned off, and with the crop taken from top left of the source image offset by 100 pixels in the horizontal and vertical directions.

The resulting image will be a sub-section of the top-left of the source image with dimensions 300px by 168px.

Illustration

{exp:jcogs_img:image crop='face_detect' face_crop_margin='50px' face_detect_sensitivity='5'}

Face Detect - Auto crop dimensions

Crop an image to focus on the face(s) found within the image using default face detection sensitivity setting, adding a crop margin of 50px in each direction.

Illustration

{exp:jcogs_img:image width='300' crop='yes|face_detect,face_detect||no' aspect_ratio='16_9' face_detect_sensitivity='5'}

Face Detect - Manually set crop dimensions

Crop an image to be 300 pixels wide with an aspect ratio of 16:9 with smart scaling turned off, and with the crop centered on the center of faces detected in the image.

Sets the default width to use when processing an image where the source image file that does not include such width information: not all SVG image files contain this information. Some do, others just an aspect ratio (but no base width) and some no information at all. 

The value can be given as an integer number (of pixels) with or without a trailing px suffix.

If the source image contains height information that value will be used to set the original height value for the image.

If the source image contains aspect ratio information, the original height value will be estimated by multplying the original width by the aspect ratio.

If no information about height or aspect ratio is provided this value will be used as. 

This parameter will over-ride the default value set for the tag during the processing of the image tag it relates to.

Sets the default width to use when processing an image where the source image file that does not include such width information: not all SVG image files contain this information. Some do, others just an aspect ratio (but no base width) and some no information at all. 

The value can be given as an integer number (of pixels) with or without a trailing px suffix.

If the source SVG image contains width information that value will be used to set the original width value for the image, otherwise this value will be used as the default width (in px). This parameter will over-rides the default value set for the tag during the processing of the image tag it relates to.

Determines whether JCOGS Image will check to see if the user's browser is able to display the processed image format selected.

This parameter can be used to over-ride the default setting for this behaviour set in the add-on's control panel area.

When set, this parameter instructs JCOGS Image to add a margin to the area detected when using the face detect feature in the crop parameter or the face_detect filter.

The value can be specified using any valid JCOGS Image Dimension format - as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image width.

The default value used is 0.

When set, this parameter instructs JCOGS Image to adjust the sensitivity factor used during face detection activities associated with use of the face_detect filter and the crop parameter.

The value is specified as an integer value between 1 and 9, where 1 is the least sensitive setting and 9 is the most sensitive. The higher the sensitivity value the harder Image works to detect faces in an image; working harder translates into longer image processing times. Higher values can result in a face being detected that is not recognised using lower values. 

The default value for this parameter is 3.

Defines a fallback image source to be used in cases where either the src= parameter is not specified, or is specified but the information provided does not point to a valid image.

This parameter is useful in cases where the developer cannot always be sure that the intended image data will always be available.

Fallback information can also be specified via the system default values set through the add-on control panel; the fallback source specified within a tag will have priority over the default value.

The fallback image source can defined using:

• the content of any ExpressionEngine File variable (or similar from an ExpressionEngine add-on field type)
• a path to file stored on the server that ExpressionEngine is running on. Local paths will be evaluated relative to the web root folder.
• a URL pointing to a file stored on a remote system
• a text string containing an appropriate EE database File record.

Remote files are cached locally during processing but only the processed version of the image is cached.

It is not important whether the source image file has an extension, or whether the given extension is correct - JCOGS Image validates each image before processing, a step that includes determining the actual image format being used to ensure that the image is in a format that the local ExpressionEngine server can work with.

The format options available are determined by the abilities of the php image processing library used: for GD2 (the default library used by JCOGS Image) the available formats are:

Later versions of JCOGS Image will support other graphics libraries, which if installed may give access to other image formats.

Allows you to specify the filename prefix you would like the processed image to use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify an alternative to for the original filename of the image.  Note: this does not replace the full filename of the processed image, just the initial element.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename='Cats_Make_Curious_Companions' the processed image filename would be Cats_Make_Curious_Companions__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Allows you to specify a prefix to add to filename the processed image will use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify a prefix to be added to the original filename of the image.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename_prefix='Cats_' the processed image filename would be `Cats_our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Allows you to specify a suffix to be appended to the filename the processed image will use.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

This parameter allows you to specify a suffix to add to for the original filename of the image.  Note: adds the suffix to the original filename, it does not add a suffix to the whole processed image filename.

For example, an image with the original name our_office.jpg when processed might be given the filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.  When the tag generating the image includes the parameter filename_suffix='_likes_cats' the processed image filename would be `our_office_likes_cats__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Allows for the specification of one or more filters to be applied to the image during processing.

The syntax for this parameter comprises a series of pipe (|) separated sub-parameter blocks - each sub-parameter block relating to a filter you want to apply.

Filters are applied to the image in the order that they are specified in the filter parameter.

As each filter has its own parameters the definition of the sub-parameters is discussed in more detail in the separate filters section of this document.

Illustration

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

In this example the image has a colorize filter applied followed by a blur filter.

If two image dimensions are given (or implied) in a JCOGS Image and crop is not also specified, this tag determines how the image is scaled relative to the two dimensions.

The parameter can take one of three values: 

• contain  The image is scaled to fit within the box defined by the two dimensions given (or imputed) while maintaining the image aspect ratio. This is likely to result in a image that is smaller than the area defined by the bounding box. This is the default value.
• cover The image is scaled to completely fill the box on both dimensions, but is not cropped (so the larger dimension will exceed the dimensions of the box provided). This is likely to result in an image that is larger than teh area defined by the bounding box.
• distort The image dimensions are preserved and the image is allowed to be distorted to fit into the space defined.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='contain'}

Contain

The image is scaled to fit within the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='cover'}

Cover

The image is scaled to fill the 300x300 bounding box specified.

Illustration

{exp:jcogs_img:image width='300' height='300' fit='distort'}

Distort

The image is distorted to fit within the 300x300 bounding box specified.

Instructs JCOGS Image to flip the image content around either the vertical or horizontal axis (or both).

Illustration

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

Flip the image about the vertical axis.

JCOGS Image names the processed images it generates using a combination of a filename and some special characters used to support reliable cache operations: this combination preserves potentially useful file naming information for Search Engines while allowing JCOGS Image to attach the cache related information it needs to the processed image filename.

For example, a file with the original name our_office.jpg might be given an output filename of our_office__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg

This parameter allows you to obscure the original of the image in the output filename - the original name is replaced by a hash. Possible values are "yes" and "no", with the default being "no".

When enabled, this option would result in an output filename for our example image becoming something like 1d48854ed203acf437ef4a09c1112973fd5c9ad6__-_2710_-_0a257337af443a3a347dcd528e6b77f6dccf82d4.jpg.

Sets the height of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image height.

If the value is not specified, JCOGS Image will try to impute a value for height from other parameters specified.

Illustration

{exp:jcogs_img:image height='150px'}

Set the height of the image to 150px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.

Enter a prefix for the published path to a processed image.
If entered, this value will be prefixed to the processed image path in all HTML tags generated by JCOGS Image and will also made available via the {made_with_prefix} variable.
Note: Even if specified here, the prefix will only be added to a JCOGS Image tag that has the parameter use_image_path_prefix='yes' set, otherwise this value is ignored.
A default value for this setting can be set within the Default Settings section of the Add-on Control Panel area.

When this parameter is set to ‘yes’ it instructs JCOGS Image to save the processed image as an interlaced (or ‘progressive’) jpg image.

Instructs JCOGS Image to configure the <img> tag created to ‘lazy load’.

Lazy-loading is a technique to speed up the loading of image intensive pages: the loading of full-size images is deferred while the image is outside the part of the screen currently being viewed by the user.

JCOGS Image's approach to lazy-loading is one that is performant and offers strong compatibility with current browsers:

• it activates the HTML5 loading="lazy" parameter in image tags it creates - which defers loading image files until they come close to the browser viewport: by not downloading images that cannot be seen this reduces the amount of content that has to be downloaded from the server prior to rendering the page
• it replaces the processed image within the <img> tag with a placeholder image created from the processed image; these are images that have the same dimensions as the processed image but are either a low-resolution version of that image, or a plain colour field that is keyed to the ‘dominant colour’ of the processed image. This placeholder image has the same dimensions as the processed image but is much smaller than the original image
• it also loads a small javascript utility with the page which monitors whether an image is ‘in-view’ and replaces the placeholder image with the full-resolution processed image just before the image appears on screen.

The method used works and for the most-part is transparent to the user.

Lazy-loading can be set as a system option in the add-on control panel, and / or be set by adding the lazy= parameter to a tag.  There are four options for the tag:

• no - turns off lazy-loading for this tag - over-rules any system default that has been set
• html5 - turns on lazy-loading via the HTML5 loading=lazy option, but does not enable placeholder image substitution
• lqip - low quality image placeholder - turns on lazy-loading and instructs that the placeholder image should be a representative of the processed image, but much smaller (typically between one quarter and one sixth of the size of the processed image it is replacing)
• dominant_color - turns on lazy-loading and instructs that the placeholder image should be a simple colour-field using the ‘dominant colour’ of the processed image - such simple colour fields are very much smaller than the image they replace - often being less than one twentieth of the size of the processed image being replaced

JCOGS Images' lazy-loading system is completely compatible with its responsive image options delivered via the srcset= option.

A more detailed discussion of how JCOGS Image's lazy-loading mechanism works is given in the Advanced Topic “Lazy Loading”.

Illustration

For more information about how JCOGS Image has implemented lazy-loading, see the Advanced Topic entry “Lazy Loading”.

Sets a maximum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image max="200" width="400" height="400" max_height="350" crop="yes"}

This tag will produce an image with dimensions 200x350.

The  max= parameter value over-rules the width= parameter value

The  max_height= parameter value over-rules the max= parameter value.

Sets a maximum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image height="270px" max_height="220"}

Limit the maximum height of the image to 220px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 220px and the aspect ratio of the original image is maintained.

Sets a maximum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image width='300' max_width='280px'}

Limit the maximum width of the image to 280px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 280px and the aspect ratio of the original image is maintained.

Sets a minimum value for the width and height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image min="250" width="200" height="200" min_height="230" crop="yes"}

This tag will produce an image with dimensions 250x230.

The  min= parameter value over-rules the width= parameter value

The  min_height= parameter value over-rules the min= parameter value.

Sets a minimum value for the height of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image height="220px" min_height="250"}

Limit the minimum height of the image to 250px.

The height= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a height of 250px and the aspect ratio of the original image is maintained.

Sets a minimum value for the width of the image after processing. 

The value should be specified either as a positive integer value with no units (px assumed), or as a positive integer value with either px or % as a suffix.

Illustration

{exp:jcogs_img:image width="220px" min_width="250"}

Limit the minimum width of the image to 250px.

The width= figure given is over-ruled by this parameter.  Since no other information is specified, the image is rescaled to give a width of 250px and the aspect ratio of the original image is maintained.

Causes the output of a tag to be determined by a string entered into this parameter: any JCOGS Image Variables encountered are replaced by values derived from the source image and the manipulations specified for this tag by other parameters.

When set to ‘yes’ this parameter causes JCOGS Image to regenerate the image from the source regardless of other cache settings.

When set, this parameter instructs JCOGS Image to save the processed png image as with the specified quality level.

A quality value of 0 gives no compression and the highest quality output. As you increase the quality value, compression rates increase giving smaller file sizes but also lower quality images. The maximum png_quality value that can be used is 9.

The default value used by JCOGS Image is a png_quality level of 6.

When set, this parameter instructs JCOGS Image to save the processed image as with the specified quality level.

A quality value of 100 gives the highest quality output; lower quality values give lower quality output but usually the filesize of the images produced is also smaller.

The default value used by JCOGS Image is a quality level of 90.

There is more information about the image formats that are supported by JCOGS Image in this advanced topic on image formats.

Adds a simulated reflection of the image below the main image.

The parameter accepts up to four sub-parameters to control aspects of how the reflection is created:

• gap height: a vertical separation between the bottom of the image and the start of the reflection. Can be specified using any valid JCOGS Image dimension value; if a % value is specified it is evaluated relative to the height of the image being reflected. Default value: 0;
• start opacity: the opacity of the reflected image at the top of the reflected image (i.e. ‘closest’ to the image being reflected). The value should be specified as an integer between 0 (fully transparent) and 100 (fully opaque). Default value: 80;
• end opacity: the opacity of the reflected image at the bottom of the reflection (i.e. furthest away from the image being reflected). The value should be specified as an integer between 0 (fully transparent) and 100 (fully opaque). Default value: 0;
• reflection height: The height of the reflected image.Can be specified using any valid JCOGS Image dimension value; if a % value is specified it is evaluated relative to the height of the image being reflected. Default value: 50%;

If the reflection is applied to an image that is saved in a format that supports transparency (e.g. webp, png) then the image background is set to be transparent.

If the reflection is applied to an image that is saved in a format that does not support transparency (e.g. jpg) then the background behind the reflection is coloured using the default background colour, or whatever colour is specified in the tag using the bg_color= parameter.

Illustration

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

Reflection using default parameters

Illustration

{exp:jcogs_img:image width='300' reflection='20px,70,10,60%'}

Reflection using all available parameters

This parameter determines the amount of rotation to be applied to an image.

The rotation is specified using a single positive or negative integer value to represent the angle of rotation (in degrees) required. Rotation is measured from the horizontal, moving in an anti-clockwise direction.

As the picture rotates, the size of the containing rectangle enlarges to allow the rotated image to sit on the page without distortion, exposing some parts of this containing rectangle: the background colour of this containing rectangle is defined either by the background colour set for the tag - which can be set either within the tag using the bg_color= parameter - the default background colour set in the JCOGS Image Control Panel Settings area.

Illustration

{exp:jcogs_img:image width='300' rotate="30" bg_color="4a2d14"}

The image is rotated 30° from the horizontal. The background area exposed by the rotation is coloured #4a2d14.

Note that the size of the output image is larger than the dimensions specified in the tag parameters.

This parameter allows you to apply a radius based filter to one or more corners of an image, to give an image rounded corner(s) each with a separately defined radius. As with other filtering operations if you are saving an image in a format that supports transparency (i.e. webp, png) the area removed to create the corner will be transparent, otherwise the default background colour will be used.

Corners are identified via a short code:

• tl - the top-left corner
• tr - the top-right corner
• bl - the bottom-left corner
• br - the bottom-right corner
• all - set all the corners to the same radius

If corner values are defined more than once in a parameter, the instance defined last in the string will be the one used.

The radius to use for the corner is specified using any valid JCOGS Image Dimension (i.e. integer, px, %)

Illustration

{exp:jcogs_img:image width='300' rounded_corners='all,30' save_type='webp'}

Apply a 30px radius to all four corners.

Illustration

{exp:jcogs_img:image width='300' rounded_corners='all,30' bg_color='rgb(250,76,5)' save_type='jpg'}

Apply a 30px radius to all four corners.

Image format specified does not support transparency, so background colour value used.

Illustration

{exp:jcogs_img:image width='300' rounded_corners="all,20px|br,30%" save_type="webp"}

Combine ‘all’ and ‘br’ values to set a different corner value in one corner

Illustration

{exp:jcogs_img:image width='300' rounded_corners="all,20px|br,30%" save_type="webp" border="10|rgb(250,176,5)"}

Borders can be applied to images with rounded corners.

Determines the encoding format to be used by the processed image.

The format options available are determined by the abilities of the php image processing library used on the server running the EE instance. JCOGS Image actively monitors the available formats and only makes available formats that are supported: the formats available are listed in the JCOGS Image Control Panel settings page in the drop-down for ‘Default Image Format’ (which also ensures that the Default Image Format is always one that can be processed by the server!).

If you specify an image format in a JCOGS Image save_type that is not supported by the server, JCOGS Image will use the Default Image Format to encode the image instead, or will retain the format of source if a default is not specified.

For GD2 (the default library used by JCOGS Image) commonly available formats include:

For an image to be seen in a browser it is also important that the browser viewing the web page also supports the image format chosen. Where possible, when processing an image JCOGS Image actively checks that the current browser is able to display the format chosen; if the browser would not be able to display the image format chosen JCOGS Image substitutes a format that is supported both by the server and the browser (usually JPG).

The choice of which image formats to use when is a complex discussion area, and outside the scope of this manual to consider.

Defines the image that is to be used by the tag.

The image source can defined using:

• the content of any ExpressionEngine File variable (or similar from an ExpressionEngine add-on field type)
• a path to file stored on the server that ExpressionEngine is running on. Local paths will be evaluated relative to the web root folder.
• a URL pointing to a file stored on a remote system
• a text string containing an appropriate EE database File record.

Remote files are cached locally during processing but only the processed version of the image is cached.

It is not important whether the source image file has an extension, or whether the given extension is correct - JCOGS Image validates each image before processing, a step that includes determining the actual image format being used to ensure that the image is in a format that the local ExpressionEngine server can work with.

The format options available are determined by the abilities of the php image processing library used: for GD2 (the default library used by JCOGS Image) the available formats are:

Note: JCOGS Image also has (since version 1.3.7) had the ability to open images in the HEIC format that is widely used by Apple mobile devices: when encountered, images in the HEIC format are converted to equivalent sized .jpeg format images before they are processed by JCOGS Image. Accordingly the ability of JCOGS Image to work with this image format is not dependent upon the capabilities of the php image processing library installed.

Later versions of JCOGS Image will support other graphics libraries, which if installed may give access to other image formats.

Illustration

{exp:jcogs_img:image src='media/a_word_from_our_sponsor.png'}

A tag using a local image source.

Illustration

{exp:jcogs_img:image src='https://images.unsplash.com/photo-1591871937573-74dbba515c4c?w=800&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8N3x8a2l0dGVufGVufDB8fDB8fHww'}

A tag using a remote image source.

Automatically add responsive variants of the processed image to an <img> tag via the srcset= and sizes= parameters of the HTML <img> tag.

Responsive image variants are helpful to reduce the amount of image data that is loaded by a visiting browser.  Within the HTML <img> tag:

• the srcset= parameter allows you to identify several resolution variants of a source image;
• the sizes= parameter allows you to define how the browser should preferentially download images from those specified in the srcset= parameter based on the rendered size of the image space that the the <img> tag is trying to fill.

Tip: Mozilla's Dev site has a good introductory explanation of the principles involved.

The srcset= parameter, as used within JCOGS Image, simply takes a series of width specifications (in any dimension format understood by JCOGS Image) separated by the | pipe character. 

Note: The values given should be in order of increasing size; processing of srcset parameter values will stop when a value is encountered that is lower than the one that precedes it. 

See note below regarding how srcset interacts with the allow_scale_larger parameter.

In response, JCOGS Image will create a version of the processed image scaled (i.e. maintaining the aspect ratio of the processed image) to the each of the valid widths specified, and assemble a valid HTML <img> srcset= parameter to reference these images.

Concurrently JCOGS Image will build content for the sizes= parameter a simple rule that instructs the browser to load the first responsive variant that is greater than or equal to the real width of the image space being filled - see the illustration below for more details. If you want to define a more complicated sizes= parameter, do so and add it to your JCOGS Image tag along with your srcset= parameter; your new sizes= rule will be prefixed to the automatically generated sizes= definition in the HTML template code produced.  Since the HTML sizes= parameters are evaluated in the order they are provided and the evaluation stops after the first rule encountered for whose conditions are met, this approach ensures that any custom sizes= rule you define will take priority over the default rules generated by JCOGS Image.

Single Tag Use

When used with a single tag, Image will generate the appropriate HTML attributes required to add srcset processing to the <img> tag output.

Tag-Pair Use

When used with a tag-pair, or with the output= parameter in a single-tag use, Image will create two Image variables: {srcset_param} that contains the complete HTML <img> srcset= attribute and {sizes_param} that contains the complete HTML <img> sizes= attribute - use these to complete the srcset definition of a tag being constructed.

Illustration

{exp:jcogs_img:image width='550' srcset='250|50%|300px|400'}

The example parameters will produce an HTML <img> tag with the following content: 

    <img src="image.webp" srcset="image_250w.webp 250w, image_275w.webp 275w, image_300w.webp 300w, image_400w.webp 400w, image.webp 401w" sizes="(max-width:250px) 250px, (max-width:275px) 275px, (max-width:300px) 300px, (max-width:400px) 400px, 401px">

JCOGS Image has created an entry in the srcset= parameter within the <img> tag for each of the size options included in the parameter within the JCOGS Image tag, and a simple default sizes= parameter.

Determines whether SVG format image sources are processed or ignored.

When this option is enabled, JCOGS Image will generate an output file based from a source SVG file - the svg file itself is simply copied from the source to the JCOGS Image cache directory, but some of the requested parameters are acted upon. This behaviour is designed primarily to allow SVG images to be included in media collections, such that if they are included as source files Image generates some output rather than the previous behaviour (and still the default) of producing of none.

For a more complete discussion of JCOGS Image's support for SVG image format, there is an Advanced Topic entry about this.

Overlays text on an image. 

This parameter gives options to control font, colour, size, position of the text relative to the background image, and whether to add a shadow to the text. Text added is is word-wrapped within either the containing box of the image, or within a narrower box if a width adjustment is specified.

There is much information needed to define what text to overlay on the image, and so the parameter string for this is necessarily complex, containing up to 16 elements (two more than in the CE Image equivalent); however only one is mandatory (the text to overlay).  The elements should be separated by the pipe character (|) and are (in the order they need to be included in the parameter):

• the text to add - any string of characters and spaces enclosed.  If the text is directly entered it cannot include any pipe ('|') characters (as this gets confused with the element separator), but these characters can be included if the text added as an EE variable.
• minimum width / height - can set the minimum size the target image has to have for the text to be added - if omitted or set to zero text will always be added. Values can be any valid JCOGS Image dimension: if a % value is specified it will be calculated based on the width of the processed image. If omitted, both values default to zero.
• font_size - the size of the font to use. Can be specified in terms of pixels or points (add pt sufix to number). If omitted the value defaults to 12px.
• line_height - the height of the line to use - controls the vertical spacing of text. Can be specified using any valid JCOGS Image dimension (so integer, px, %): if a % specified, it is converted to a pixel value relative to the font size specified. If omitted the default value is 1.25 (so a default line height of 15px).
• font_color - the colour to use for the text added. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to white.
• font_src - the relative path from your site's web root folder to the font file that you want to use for the text added. The font file should be a true-type font file (ttf). If omitted the value defaults to Voces Regular.
• text_align - determines how the text will be aligned within the text-box area. Options are left, center and right. If omitted the value defaults to center.
• width_adjustment - allows you to specify a width-adjustment for the box that encloses the overlayed text. Can be specified using any valid JCOGS Image dimension (integer, integer+px, %). Positve values are read as the width that you want the text box to have (so 40% would indicate a width for the text equal to 40% of the width of the processed image). Negative values are read as the reduction in size from the width of the processed image - (so -40% would indicate a width for the text equal to 60% of the width of the processed image).  % values are translated based on the width of the processed image. Values that define a width greater than that of the processed image will be ignored.
• position - set the horizontal and vertical position for the text box within the image box. Options for horizontal are left, center, right.  Options for vertical are top, center, bottom. If omitted these values default to center.
• offset - set a horizontal and vertical offset from the general position specified for the location of the text-box.  Values can be entered using any valid JCOGS Image dimension format, if a % value is specified it will be calculated relative to the width of the processed image. So an offset of -20px,10% would cause the text box to be moved left by 20px, and up by 10% of the width of the image from the location defined by the position parameter. If omitted the values default to zero.
• opacity - set the opacity for the text to be added. Value must be an integer between 0 (transparent) and 100 (opaque). This value will over-rule by any opacity set in the font_color parameter. If opacity is omitted and no font_color opacity is specified the value defaults to 100, otherwise the font_color opacity specified is used.
• shadow_color - set an colour for a shadow to be placed behind the text added. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
• shadow_offset - sets a horizontal and vertical offset for any text shadow. Specified as a pixel offset from the text using any valid JCOGS Image dimension format (if a % is specified, it is translated into pixels using the width of the processed image as the base value). So a value of 2,1 translates to a horizontal offset of 2 pixels, and a vertical offset of 1 pixel. If this value is omitted, the values each default to 1 pixel.
• shadow_opacity - sets the opacity of the shadow colour. Value must be an integer between 0 (transparent) and 100 (opaque).. This value will over-rule by any opacity set in the shadow_color parameter. If opacity is omitted and no shadow_color opacity is specified the value defaults to 100, otherwise the shadow_color opacity specified is used.
• text_box_bg_color - sets a background colour for the box containing the overlaid text. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
• text_bg_color - sets a background colour for the overlaid text. Can be specified using any valid JCOGS Image colour format (so any hex-code, or rgb() or rgba()). If omitted the value defaults to transparent.
• rotation - sets a rotation for the box containing the overlaid text. An integer value defining number of degrees to rotate text box by; positive values translate to anti-clockwise rotation. If omitted the value defaults to no rotation.

Illustration

{exp:jcogs_img:image text = 'Sometimes text is worth adding to a picture|0,0|20px|125%|rgba(224, 225, 220, 1.0)||center|40%|right,top|0,0|100|#dcdcdc|1,1|60|rgba(100,100,30,0.3)' width='550'}

This tag will add a text box containing some text in colour rgba(224, 225, 220, 1.0) centered over a picture and then offset by -50px in horizontal and vertical directions. The text will use the default at 20px size, with line height of 25px within a text box with a background colour of rgba(100,100,30,0.3) limited in width to 40% of the width of the processed image it overlays.  The text will have a #dcdcdc colour shadow offset by 1px vertically and horizontally. 

Illustration

{exp:jcogs_img:image text = 'Feature!|0,0|45px|125%|#FFF|fonts/Lobster-Regular.ttf|center|60%|left,top|-60,-60|100|#000|1,1|60|rgba(205, 127, 131, 1.0)||45' width='550'}

This tag uses the font, rotation and text-offset sub-parameters to add a promotional flash to an image.

The text font is Lobster Regular a True Type font.

If this parameter is set to yes then the source image will be processed according to the parameters set within the tag and the only output will be a URL pointing to the processed image on the host server.

Instructs Image to apply any image path prefix given (either as a parameter or as a default value in the Default Settings section of the Add-on Control Panel area.

Overlay a watermark on an image.

This parameter allows you to specify a second image that is then overlaid on top of the primary source image, adjusting the relatively position and opacity of the image to be overlaid. It is also possible to specify for a watermark image to be repeated with a definable offset.

There is much information needed to define how to execute this requirement, and so the parameter string for it is necessarily complex. The elements that make up this parameter should be separated by the pipe character (|) and are (in the order they need to be included in the parameter): 

• watermark_src - the image source to be used for the watermark. Can be any valid JCOGS Image source (local or remote).
• minimum_dimensions - sets the minimum size the target image has to be for the watermark to be added - if omitted or set to zero the watermark will always be added. Values can be any valid JCOGS Image dimension: if a % value is specified it will be calculated based on the width of the processed image. If omitted, both values default to zero.
• opacity - the opacity for the image to be overlaid. Value must be an integer between 0 (transparent) and 100 (opaque). If omitted or an invalid value supplied, the value defaults to 100.
• position - set the horizontal and vertical position for the watermark within the image frame. Options for horizontal are left, center, right.  Options for vertical are top, center, bottom. If omitted these values default to center. 
  It is also possible to specify the horizontal position as repeat which triggers the generation of multiple instances of the watermark.
  If repeat is specified, it can optionally be followed by one or two dimension parameters which if specified set the spacing between repeated watermarks.  Any valid JCOGS Image dimension value can be used; if a % value is specified it will be calculated relative to the width or height of the watermark image. If values for the repeat offset are not specified, the horizontal offset defaults to 50% of the width of the watermark, the vertical offset to 0.
• offset - set a horizontal and vertical offset from the position specified for the location of the watermark.  Values can be entered using any valid JCOGS Image dimension format, if a % value is specified it will be calculated relative to the width of the processed image. So an offset of -20px,10% would cause the watermark to be moved left by 20px, and up by 10% of the width of the image from the location defined by the position parameter. If omitted the values default to zero. In the case where horizontal position is specified to be repeat, the offset values are applied to the starting point of the first image in the repeat sequence.
• rotation - rotate the watermark image by an integer number of degrees. Rotation direction is anti-clockwise.

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.png|0,0|50|right,bottom|0,0" width="550"}

Add a single watermark to an image.

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.webp|0,0|50|right,bottom|0,0|50" width="550"}

Add a single watermark to an image with watermark image rotated by 50°

Illustration

{exp:jcogs_img:image watermark="/media/a_word_from_our_sponsor.png|0,0|50|repeat,30,20|0,0|none" width="550"}

Add a repeated watermark to an image.

Sets the width of the image to be produced.  The value can be given as an integer number (of pixels) with or without a trailing px suffix, or as a percentage value (an integer with a trailing %). If a percentage is specified, it is converted into a pixel value by multiplying the percentage value by the original image width.

If the value is not specified, JCOGS Image will try to impute a value for width from other parameters specified.

Illustration

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

Set the width of the image to 300px.

Since no other information is given, JCOGS Image will scale the image in proportion to its original dimensions to give the height requested.