`

JCOGS Image

Introduction

JCOGS Image is a simple to use tag based image processing add-on for ExpressionEngine 5 and 6. It is fast, efficient and provides a range of image manipulation options that go beyond those available within EE's built in image processing services.

Broadly the facilities offered by JCOGS Image fall into three categories:

  • Conversion
    JCOGS Image can perform on-the-fly conversion of image formats (e.g. jpg to png). Currently it supports png, jpg, gif, bmp and webp image formats.
  • Resizing
    JCOGS Image can crop and resize images and includes the ability to preserve an image's aspect ratio or distort it as required. Image cropping can use nominated aspect ratios, and can be combined with rescaling.
  • Manipulations
    JCOGS Image can apply a range of image effects to an image, including reflection around horizontal or vertical axis, rotation, and the application of a range of image filters (e.g. greyscale, blur etc). Filters can be combined sequentially, and can be applied to converted / resized images.

**Batch Processing**

JCOGS Image can be applied to single image instances or collections of images (to which the same modifications are applied).

CE Image compatibility

JCOGS Image has strong compatibility with the stalwart CE Image add-on, offering developers a simpler upgrade path to EE5 and EE6 for sites developed using the CE-Img add-on.

Drop-in compatibility

Although JCOGS Image is based on a completely new image processing code base, it is possible to upgrade an existing site to JCOGS Image without loss of function simply doing a search / replace on the CE Image tag name - so for example {exp:ce_img:single...} would change to {exp:jcogs_img:single...}. In most cases the templates will generate output similar to that produced with CE Image.

Note: Some CE Image functions are not replicated (e.g. ASCIIart) and for some advanced uses (e.g. filters) there are some differences in how some settings work. Sections later in this document for more complete compatibility information.

Requirements

JCOGS Image has been tested and is supported for use on EE5 and EE6 systems. It requires the server hosting the EE installtion to be running php 7.3 (or better) and some version of the GD2 library.

Installation

Copy the jcogs_img folder to your system/user/addons folder and then install from the ExpressionEngine Control Panel Add-ons page.

Configuration

The add-on can be used 'out of the box' without further configuration; most settings can be adjusted on a case by case basis by parameters added to the JCOGS Image tag. The Control Panel settings area is used to set key default values.

Main Settings

Enable JCOGS Image - Does what it says on the tin...

Default Cache Directory - Sets the directory (relative to the site web root / public_html directory) to use to store the images generated by JCOGS Image. The default location is images/jcogs_img. If directory chosen does not already exist JCOGS Image will try to create it. This setting can be over-ridden on a tag by tag basis via the parameter cache_dir=.

Default duration for cached images - By default, images generated by JCOGS Image are cached (to avoid having to recreate them every time a template is run). This option sets the default value (in seconds) for how long cached images are kept. The default value is -1 which gives a perpetual cache (images never expire). To turn off default caching activity set this value to 0.

Default quality for JPG images - By default jpg images generated by JCOGS Image use the quality factor 90. Change the default using this option. This setting can be over-ridden on a tag by tag basis via the parameter quality=.

Default background colour - JCOGS Image will preserve transparency if suitable image formats are chosen, but when an image is converted from transparent to solid, or a manipulation forces part of the background to be exposed (e.g. via rotation operation) this option determines the apparent colour of the background layer. It defaults to white (#FFFFFF). This setting can be over-ridden on a tag by tag basis via the parameter bg_color=.

Enable Debugging Messages in Template Log. - When enabled, helpful messages are placed in the template debug log as JCOGS Image processes images.

Usage

JCOGS Image is an image processing utility. At it simplest it translates JCOGS Image tags into correctly formed <img>; all you need to do is provide the tag with a path to the source image. The source image can provided by EE (e.g. via a files field), or a URL. For example, for a channel with a file field called images:

{exp:jcogs_img:image src="{images}" }

will render as:

<code><img src="https://domain.com/media/jcogs_img/test_image_5cb969efbda33df285a33c09735e6594cbf6b5c4.jpg">
</code>

The power of JCOGS Image is that you can add a host of parameters to the tag to generate modified images, and have fine control over what information is returned to EE about the image, either within the tag output (if required) or just within the EE template parse output.

JCOGS Image also provides a range of tag syntax options to accommodate different template layout conditions.

Single tag

{exp:jcogs_img:single}

The image is linked to the content of a single JCOGS Image tag, with all the relevant parameters included within the tag itself. For example:

{exp:jcogs_img:single 
    src='{images}' 
    height='80%' 
    width='700px' 
    save_type='webp' 
    aspect_ratio='16_9' 
    crop='y' 
    allow_scale_larger='y' 
    max='400' 
    class='kittens' 
    add_dims="y" 
    flip='v'}

will generate an <img> like this:

<code><img
    src="/media/jcogs_img/50802526853_0c0cdb05d0_c_9fbbd5d040c0ba1ebaca3985d7cf8b40506ccaaa.webp" 
    class="kittens" 
    width="400" 
    height="225"
>
</code>

Where https://domain.com/media/jcogs_img/50802526853_0c0cdb05d0_c_9fbbd5d040c0ba1ebaca3985d7cf8b40506ccaaa.webp points to a cached local webp file that contains a 16x9 cropped version of the original image shrunk to 400px wide and flipped vertically. The default 'smart scale' crop means the image height is also reduced to maintian the requested 16x9 aspect ratio (over-riding both the height and max parameters) and avoiding image distortion.

To avoid any parsing confusion within the EE parse system, JCOGS Image single tags can use either image or single as the opening / closing tag element as required.

Pair tag

{exp:jcogs_img:pair} ... {/exp:jcogs_img:pair}

The image information can also be provided via a pair of tags (opening / closing). In this circumstance JCOGS Image will process any parameters specified in the opening tag, and will parse the contents enclosed by the tag and substitute image related parameters for any JCOGS Image variable tags encountered. This approach allows you to create your own customised HTML output.

For example:

{exp:jcogs_img:image 
    src='{images}' 
    width='900px' 
    height='800px' 
    max_width="777px" 
    min="340px" 
    aspect_ratio='16_9' 
    crop='y' 
    save_type='webp' 
    allow_scale_larger='y' 
    class='cats' 
    rotate="65"
    flip='h'}

<img src="{made}" {attributes} width="{width}" height="{height}"/>

    
    {/exp:jcogs_img:image}

will generate an <img> like this:

<code><img 
    src="/media/jcogs_img/50802526853_0c0cdb05d0_c_52eef17e88ec6541ff432ac461a62cb9a1596628.webp" 
    class="cats" 
    width="723" 
    height="888"
>
</code>

To avoid any parsing confusion within the EE parse system, JCOGS Image tag pairs can use either image or pair as the opening / closing tag element as required.

Bulk tag

{exp:jcogs_img:bulk} ... {/exp:jcogs_img:bulk}

This tag searchs the content enclosed by its opening / closing tags for <img> tags; any tags found will be processed by JCOGS Image using the parameters found in the opening bulk tag. If width or height parameters are specified within any of the <img> tags found, they will over-ride the values set in the bulk tag (if any).

The bulk tag is useful if you want to apply 'standard' modifications to images within a content block (e.g. making all the images the same size / aspect ratio, applying a class to each image etc.).

For example:

{exp:jcogs_img:bulk 
    width='900px' 
    height='800px' 
    max_width="777px" 
    min="340px" 
    aspect_ratio='16_9' 
    crop='y' 
    save_type='webp' 
    allow_scale_larger='y' 
    class='cats' 
    rotate="65"
    flip='h'}
<code>    <p>Macavity, Macavity, there’s no one like Macavity,
    There never was a Cat of such deceitfulness and suavity.</p>
    <img src="{images}" width="700px">
    <p>He always has an alibi, and one or two to spare:
    At whatever time the deed took place—MACAVITY WASN’T THERE!</p>
    <img src="https://placekitten.com/400/600">
</code>
    {/exp:jcogs_img:bulk}

will generate HTML output like this:

<code>    <p>Macavity, Macavity, there’s no one like Macavity,
    There never was a Cat of such deceitfulness and suavity.</p>
    <img src="/media/jcogs_img/50802526853_0c0cdb05d0_c_42139d0677052065d989980f2e73fd284d253c87.webp" class="cats">
    <p>He always has an alibi, and one or two to spare:
    At whatever time the deed took place—MACAVITY WASN’T THERE!</p>
    <img src="/media/jcogs_img/600_42139d0677052065d989980f2e73fd284d253c87.webp" class="cats">
</code>

Note that bulk tag processing has processed and cached locally one local image (the first one in the example) and one image obtained from the web - JCOGS Image works equally well with either kind of image source.

Parameter & Variable Reference

The parameters and variable definitions for all three tag types are the same.

Some parameters and variables are marked with CE in first column. These parameters are named identically and have equivalent function to CE-Image parameters of the same name; implementation differences are noted in comments next to each.

Parameters

Parameters are optional - use them within your JCOGS Image tags to modify the image processing to be carried out by the add-on.

ParameterNotes
CEadd_dimsyes or no If added to a tag, will cause dimension parameters to be added to <img> tag if you choose options that will create such output.
CEallow_scale_largeryes|no Only applies to resize operations
aspect_ratiohorizontal_vertical Horizontal and vertical scalar values (e.g. 16_9, 16:9 16/9) used to calculate aspect ratio to use. Applies only in crop operations.
CEattributesany valid HTML parameters Content is passed through to output unchanged if <img> tag created or are available via the {attributes} variable if not.
CEbg_colorhex colour code Really only useful for rotate operations currently.
cacheinteger Time (in seconds) to cache processed image for. Over-rides Control Panel / Default setting. -1 give perpetual cache, 0 gives no cache.
CEcache_dirpath from HTML root to directory Over-rides Control Panel / Default setting
CEcreate_tagyes|no If set to 'yes' JCOGS Image will output an <img> tag based on input parameters provided.
CEcropy/n|h-position[left,center,right],v-position[top,center,bottom]|x-offset(px),y-offset(px)|smart-scale[y/n] Crop plus support for 'smart-scale' and aspect ratio control of output.
CEfallback_srcany valid image source Source can be any local file or one obtained via a URL. Remote files are cached locally during processing but only the processed version of the image is cached.
CEfilterpipe separated list of filters followed by filter parameters Equivalent filters provided for brightness, colorize (no alpha), contrast, guassian_blur, grayscale, invert, negate, opacity, pixelate, sharpen. CE Compatability Note: Variable ranges where used are changed to -100 -> 100 from -255 -> 255. See separate notes on filters for more details of how to configure individual filters.
fitcontain|cover|distort Coming soon... If two image dimensions are given and crop is not chosen, determines whether image is scaled to fit completely into dimension (contain), or scaled to ensure image extends to all edges of bounding box without distortion (cover), or is distorted to fit into space defined.
CEfliph|v Flips image across horizontal or vertical planes. h|v will result in boht flips being performed sequentially.
CEhash_filenameyes|no JCOGS Image uses a different approach to file names, but an equivalent option is implemented.
CEheight500|50%|500px Specify as integer pixel count (e.g. 500 or 500px) or % (of source image height) (e.g. 50%).
CEinterlaceyes|no If JPG output format is chosen (save_type='jpg') will cause interlaced JPG format to be used.
CEmax500|50%|500px May override width and height parameters if they are set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image width) (e.g. 50%).
CEmax_height500|50%|500px Overrides max if set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image height) (e.g. 50%).
CEmax_width500|50%|500px Overrides max if set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image width) (e.g. 50%)
CEmin500|50%|500px May override width and height parameters if they are set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image width) (e.g. 50%).
CEmin_height500|50%|500px Overrides min if set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image height) (e.g. 50%).
CEmin_width500|50%|500px Overrides min if set. Specify as integer pixel count (e.g. 500 or 500px) or % (of source image width) (e.g. 50%).
CEoutputstring containing text and JCOGS Image variables Causes JCOGS Image to output a parsed string - allows a single tag to give similar output to a tag-pair.
CEoverwrite_cacheyes|no If yes forces new copy of image to be created regardless of caching settings.
CEqualityinteger Default value (for jpg files) set at 90.
CErotateinteger Simple rotate, angle measured from from horizontal going anti-clockwise.
CEsave_typeformat Formats supported: gif, jpeg, png, bmp, webp, jpg. Default: jpg.
CEsrcany valid image source Source can be any local file or one obtained via a URL. Remote files are cached locally during processing but only the processed version of the image is cached.
CEurl_onlyyes|no Image processed according to parameters specified and a URL to the image returned, other parameters not related to image processing ignored.
CEwidth500|50%|500px Specify as integer pixel count (e.g. 500 or 500px) or % (of source image width) (e.g. 50%).

Filters

The filter= parameter lets you perform more complex manipulations on your image. There are several filters defined which are described below. The format for defining a filter is consistent across all the available filters and is of the form:

filter="filter_name, parameter_1, parameter_2 ... "

To define multiple filters use the | character to join up several filter instructions. For example:

filter="sharpen,10|greyscale|blur,20"

Note for CE Image migration: If you are updating a site from CE Image many of JCOGS Image filters have the same name as equivalents in the CE Image add-on and broadly they work in the same way and so an in-place upgrade should work OK. Any CE Image filters specified in your site that have not been implemented by JCOGS Image will simply be ignored. One significant change however is that where there a filter requires use of a scalar value, these are bounded by +/- 100 rather than +/-255 so you may need to adjust these values if you are updating. The strength of effect may also be different (so sharpen,10 may produce different results between add-ons), so such value adjustments are probably needed.

FilterNotes
CEbrightnesse.g. brightness,30 Adjusts the brightness of the image. One parameter, a value in range -100 to +100. A value of 0 produces no change, positive numbers increase brightness. Default = 0.
CEcolorizee.g. colorize,30,-10,20 Adjusts the Red, Green and Blue components of an image. Three parameters, each a value in range -100 to +100. A value of 0 produces no change, positive numbers increase strength of colour. Default = 0.
CEcontraste.g. contrast,40 Adjusts the contrast of the image. One parameter, a value in range -100 to +100. A value of 0 produces no change, positive numbers increase contrast. Default = 0.
blure.g. blur,30 Applies a gaussian blur filter with a optional amount to the current image. One parameter, a value in range 0 to +100. A value of 0 produces no change, positive numbers increase amount of blur. Default = 1.
CEgaussian_blure.g. guassian_blur,30 Identical to the blur filter.
CEgrayscalee.g. grayscale Turns image into a greyscale version. No parameters.
greyscalee.g. greyscale Identical to the grayscale filter.
inverte.g. invert Reverses all colors of the current image. No parameters
CEnegatee.g. negate Identical to the invert filter.
CEopacitye.g. opacity,70 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.
CEpixelatee.g. pixelate,10 Applies a pixelation effect to the current image with a given size of pixels. One parameter, the size of the pixel block to use for the pixelation effect. A value of 0 produces no change. Default = 0.
CEsharpene.g. sharpen,10 Sharpen current image with an optional amount. One parameter, a value in range 0 to +100. A value of 0 produces no change. Default = 10.

Variables

Variables are tokens you can use to access information about the image as you process it. They are only useful within the output parameter string, or when used between JCOGS Image tag-pair.

VariableNotes
CEattributesContains content of attributes parameter if set, plus for tag-pair operations any non-JCOGS image variables enclosed by the tags.
CEbase_64A base_64 encoded copy of the processed image.
CEbase_64_origA base_64 encoded copy of the source image.
CEmadeThe relative path to the cached copy of the processed image.
CEmade_urlThe URL to the cached copy of the processed image.
CEorigThe relative path to the source image.
CEorig_urlThe URL to the source image.
CEpathThe full path to the cached copy of the processed image.
CEpath_origThe full path to the source image.
CEheightThe height in px of the processed image.
CEheight_origThe height in px of the original image.
CEwidthThe width in px of the processed image.
CEwidth_origThe width in px of the original image.
CEnameThe name of the processed image (without extension).
CEname_origThe name of the source image (without extension).
CEextensionThe filename extension of the processed image.
CEextension_origThe filename extension of the source image.
CEfilesizeThe size of the processed image in power based units (e.g. Kbytes).
CEfilesize_origThe size of the source image in power based units (e.g. Kbytes).
CEfilesize_bytesThe size of the processed image in bytes.
CEfilesize_bytes_origThe size of the source image in bytes.
CEtypeThe image format of the processed image.
CEtype_origThe image format of the source image.

Usage notes

  • Caching
    JCOGS Image tries hard to cache all the processed images to avoid repeated recalculation of the same image. JCOGS Image uses a hashing mechanism to avoid cache conflicts; this approach is different to the one used by CE Image. Processed image names have two components; the original image name followed by a hash-string based on the the parameters and their values used to create it - e.g. cat-picture-12_68abecea94701221fb9f925847f4fc7e5b28be23. This approach aims to find a workable compromise between SEO and functional considerations. The hash_filename= parameter causes the source filename to also be hashed - to obscure the original source file name.
  • Nesting JCOGS Image tags
    It is possible to enclose JCOGS Image tags within other JCOGS Image tags, but a flaw in the parsing algorithm used by EE can make such nesting unreliable. To avoid this you can use multiple tag names. exp:jcogs_img:image, exp:jcogs_img:single and exp:jcogs_img:pair are actually functionally equivalent and can be substituted for each other without issue. If you need to nest tags, by using a different method name for the outer pair to the name used for the inner pair you will avoid any EE parsing issues.
  • Building complex <img> and <picture> tags
    Use the pair tag option and JCOGS Image variables to build complex HTML image tags: if you need multiple resolution images within the same tag, simply nest 'single' format JCOGS Image tags within the tag-pair to create the various different resolution versions of the image.

CE Image compatibility

Although JCOGS Image is based on a completely new image processing code base, JCOGS Image offers some parameter and variable compatability with the stalwart CE Image add-on: this offers developers a simpler upgrade path for sites developed using the CE-Img add-on.

Some CE-Img parameters and features are not currently supported and they are listed in the table below.

Notes
borderComing in a later version
textComing in a later version
top_colorsComing in a later version
watermarkComing in a later version
automatic variable prefixingCould be replicated if demand for this exists
manipulateCould be replicated if demand for this exists
reflectionCould be replicated if demand for this exists
ascii_artUnlikely to be replicated.
disable_xss_checkXSS checks on paths provided are not optional.
force_remoteThis behaviour is handled automatically, there is no equivalent operation
auto_cacheFile caching handled differently - see separate notes
remote_cache_timeFile caching handled differently - see separate notes
remote_dirFile caching handled differently - see separate notes
filenameJCOGS Image uses a different approach to file names
filename_prefixJCOGS Image uses a different approach to file names
filename_suffixJCOGS Image uses a different approach to file names
encode_urlsJCOGS Image uses a different approach to file names and so this is not needed
hide_relative_pathJCOGS Image uses a different approach to file names and so this is not needed
uniqueJCOGS Image uses a different approach to file names and so this is not needed.

Continuing Development

JCOGS Image already offers a strong feature set, but we are keen to develop and evolve this: if there is a feature missing from JCOGS Image let us know and we'll do our best to add it to a future version.

Support

Support is available from JCOGS Design via email sent to img_addon@jcogs.net or via @JCOGS Design the EE Slack discussion area.

Changelog

1.0.10 (20 October 2021)

First public release.