CE Image menu

Parameters

add_dims=

By default, CE Image will add in width and height attributes to the image tags it generates when using the ce_img:single tag. If you would like to disable this on a per tag basis, you can use this parameter. There is also a config variable that allows you to disable this behavior globally.

In the example below, the first image has the add_dims enabled, and the second has it disabled. This code:

{exp:ce_img:single src="/images/example/cow-sign.png" add_dims="yes"}
{exp:ce_img:single src="/images/example/cow-sign.png" add_dims="no"}

Turns into this:

<img src="/images/example/cow-sign.png" width="200" height="200" alt="" />
<img src="/images/example/cow-sign.png" alt="" />

allow_scale_larger=

Sometimes you may want an image to scale larger to fill a certain area, however, an image will not stretch larger than its original dimensions by default. This option allows the image to stretch to auto fit within the dimensions you specify, while still maintaining its aspect ratio. Accepted values are "yes" and "no", and the default is "no".

In the example below, both images are set to 300px by 300px, but the image on the left is not given permission to scale larger than its default size of 200px by 200px. The image on the right is scaled larger to fit its new dimensions.

{exp:ce_img:single src="/images/example/cow-sign.png" min="300"}
{exp:ce_img:single src="/images/example/cow-sign.png" min="300" allow_scale_larger="yes"}

ascii_art=

This parameter allows you to create ASCII art from an image. The general syntax for this parameter is: ascii_art="colorize|characters|repeat_characters|use_a_space_for transparent_pixels".

colorize: Should the generated art to be colored? Acceptable values are "yes" or "no". This is the only required sub parameter.

characters: A list of comma delimited characters (or entities) to use in the art. Defaults to #,@,%,=,+,*,:,-,.,&nbsp;. These characters should be ordered from darkest to lightest if you are not specifying the repeat sub parameter (below). Please not that you will not be able to use the following characters, as they are used in the parameter: ,, |, and ", but you can use their HTML entities, which are &#44;, &#124;, and &quot; respectively.

repeat characters: Whether or not the characters should repeat in consecutive order ("yes") or be placed depending on the darkness of the pixel ("no"). Defaults to "no".

use a space for transparent pixels: If the repeat characters parameter above is set to "yes", you can set this parameter to determine whether or not a space should be used for transparent pixels. The default is "no". Even if you are not repeating characters, you can accomplish the same thing by setting the last character of the characters sub parameter to &nbsp; (it is already in the default array).

Note: Each character represents a pixel from the image. Since the characters will be considerably larger than 1px, you should make your images very small if you will be generating ASCII art for them. In the examples below, you can see the tiny images that are used to generate the ASCII art. Of course, it all depends on the size you make your text…

Note: The actual ASCII art is not cached, although the generated image is. However, you can (and most likely should) cache the ASCII art by using ExpressionEngine®’s native tag caching. Learn more about increasing your performance using CE Image.

            .------------------------.            
         .------------------------------.         
       .-------------------------*--------.       
      ------------::-:::---..  -+:----------      
     ------------:*+**+=++-  .**-------------     
    ------------*:--  -*++*-***+++:-----------    
   -----------:*-     .-:%%+-*==+++*-----------   
  .---+*:-....:-   .... .==::=+%*:=+-----------.  
  ----:=%=++*-::-*:-     :%%==+=:*+*------------  
 .------:*+++++::++*-    .+@%+=*:++-------------. 
 ------:=@@%*-:::*++*.   -=%@%=*++*:::---------:- 
 -----:%@@@@@%=*--+++:   *+%@@=+++*::***:--:::--- 
.-----+@@@@@@@@:-.***.   +%@@@%=**::-:*:-:::::-::.
.---.-+@@@@@@@@-:--::.   =%%%%=***::::::---::::::-
----.--=@@@@@@%***-*::-  +@%%@%+**::::*:-:::::::::
--------=@@@@@%=***::::.-=%%%@@%=**:****::::::::::
---------*%@%+*-.::::::.:=%%@@@@%%*:**+**:::::::::
----..--------..-::--::.:*%%@@@@@@%=****+*:::*****
----.....----...:::---:*+:%%@@@@@@@%%=++++*::****+
--......---.....-*:---:*++=%@@@@@@@%%%%%=++***+*++
----.----........**---:::*+@@@@@@@@@@%%%%%=+******
------...........:*:.:::::*=@##@@@@@@%%%%%%%++===+
.................-*:-*:---:=%###@@@@@%%%%%%%%%%%%%
............  ....::-:-:::=@%####@@@@%%%%%%%@@@%%%
.........      ...-::---::@@=@###@@@@@%%@%%%@%@@%%
.........     .....-:=:::+#%=%##@@@@@@%%%%%%%@@@@@
..........    ..  ..-*:*+=%%%%###@@@@@%%%%%%%@@@@@
............ ...  .-.-:=@%@%%@###@@@@@%%%%%%%%@@@@
..............    ..-:=@@@@@######@@@@%%%%%%%%@@@@
....................--+%+*%@@####@@@@@%%%%%%%@@@@@
.......................   .=@####@@@@@%%%%%%%@@@@@
...........................=@##@@@@@@@%%%%%%%@@@@@
...........................+@##@@@@@@@==%%%%%@#@@@
...........................:%@#@@@@@@@==%%%%@=++=%
..................    .. ...*=@@@@@@@@==%%%%*    .
.................        .   +@#@@@%%@*+=%%%*     
 ..............              :%#@@%=%@+:+%%%*     
 ...............       .   .-:%%@@@%@@%:**=%*     
 ..............     .-*++=++=+%=%@%@@%%-**+%*     
 .........         *: *==%%==%@%=%=%===::*+=+     
 .-.:***-.         -- =@@@%=%@@%%*+=+--::**=+...  
  =+++=++:.....    .:-*#@@@@@@@@=:    .-:::+=...  
  *%===+**::**-   ..*:+##%@##@%%%+    .-::**=--.  
   =+==+++*****-:++***=@@%@@@+===%++:--::*++=::   
    ===++**+++:*++==+*+@===*=+*++++*::+::+++=:    
    .+==++=++==*+*+*+***++:::::*+++:::*:::++=     
      =%%%=++==***::*++****:::::+*+::::-::**      
       :%%+****+*++*+*+***::::::::::::::::.       
         -**+*+==%=++++**::*::::*:::::::.         
            -**=+==++=+**-::::::::::-.            

                       owcr                       
                      ssingc                      
                     cowcross                     
                    ossingcowc                    
                   gcowcrossing                   
                  rossingcowcros                  
                 ngcowcrossingcow                 
                crossingcowcrossin                
               ingcowcrossingcowcro               
              wcrossingcowcrossingco              
             singcowcrossingcowcrossi             
            owcrossingcowcrossingcowcr            
           ssingcowcrossingcowcrossingc           
          cowcrossingcowcrossingcowcross          
         ossingcowcrossingcowcrossingcowc         
        gcowcrossingcowcrossingcowcrossing        
       rossingcowcrossingcowcrossingcowcros       
      ngcowcrossingcowcrossingcowcrossingcow      
     crossingcowcrossingcowcrossingcowcrossin     
    ingcowcrossingcowcrossingcowcrossingcowcro    
   wcrossingcowcrossingcowcrossingcowcrossingco   
  singcowcrossingcowcrossingcowcrossingcowcrossi  
 owcrossingcowcrossingcowcrossingcowcrossingcowcr 
ssingcowcrossingcowcrossingcowcrossingcowcrossingc
owcrossingcowcrossingcowcrossingcowcrossingcowcros
singcowcrossingcowcrossingcowcrossingcowcrossingco
wcrossingcowcrossingcowcrossingcowcrossingcowcross
 ngcowcrossingcowcrossingcowcrossingcowcrossingco 
  ossingcowcrossingcowcrossingcowcrossingcowcros  
   owcrossingcowcrossingcowcrossingcowcrossingc   
    ingcowcrossingcowcrossingcowcrossingcowcro    
     rossingcowcrossingcowcrossingcowcrossing     
      cowcrossingcowcrossingcowcrossingcowcr      
       singcowcrossingcowcrossingcowcrossin       
        crossingcowcrossingcowcrossingcowc        
         gcowcrossingcowcrossingcowcrossi         
          ssingcowcrossingcowcrossingcow          
           wcrossingcowcrossingcowcross           
            ngcowcrossingcowcrossingco            
             ossingcowcrossingcowcros             
              owcrossingcowcrossingc              
               ingcowcrossingcowcro               
                rossingcowcrossing                
                 cowcrossingcowcr                 
                  singcowcrossin                  
                   crossingcowc                   
                    gcowcrossi                    
                     ssingcow                     
                      wcross                      
                       ngco                       

{!-- black and white, default characters, non-repeating --}
{exp:ce_img:pair src="/images/example/cow.jpg" max="50" crop="yes" save_type="png" rounded_corners="all,15" ascii_art="n" cache="yes" refresh="360"}
<img src="{made}" alt="" style="float:left" />
{if ascii_art}
<p class="ascii_art">{ascii_art}</p>
{/if}
{/exp:ce_img:pair}

{!-- colorized and repeating --}
{exp:ce_img:pair src="/images/example/cow-sign.png" height="50" save_type="png" ascii_art="yes|c,o,w,c,r,o,s,s,i,n,g|yes|yes" cache="yes" refresh="360"}
<img src="{made}" alt="" style="float:left" />
{if ascii_art}
<p class="ascii_art">{ascii_art}</p>
{/if}
{/exp:ce_img:pair}
/* The CSS used for the above samples */
.ascii_art {
font-family:monospace, Courier;
font-size:.8em;
line-height:.625em;
float:left;
}

attributes=

The attributes='' parameter can be used in conjunction with the create_tag= parameter and allows you to pass in attributes to the generated image tag. If create tag is not set to "yes" (the default is yes for single tag syntax), this parameter will be ignored.

This parameter is rarely needed, as you can pass image attributes directly into the tag and they will intelligently be applied. However, this setting can be useful to override CSS style rules.

Example:

{exp:ce_img:single src="/images/example/cow_square.jpg" attributes='class="tester" alt="The Cow" title="An attribute example"'}

Returns:

<img src="/images/example/cow_square.jpg" width="200" height="200" alt="The Cow" class="tester" title="An attribute example" />

Attributes that are passed into the attributes parameter, are intelligently applied to the image tag after the image is processed. Additionally, passing a style="" attribute into the attributes= parameter will allow you to unset or override individual CSS rules (see Overriding Image Styles for more details).

Note: Since you will most likely be using double quotes ("") to wrap your attribute values, you will generally want to use single quotes ('') to wrap the attributes= parameter’s value. Notice in the example above that single quotes are used.

Note: In EE2.x, variables passed in the attributes parameter are parsed. Unfortunately, this is not the case with EE1.x.

auto_cache=

When set, the auto_cache= parameter will create a cache directory in the directory of the source image. The manipulated images will then be cached in this directory, and not the directory specified by the cache_dir= parameter.

If the source_directory is below web root, then the auto_cache directory will be created in the directory specified by the cache_dir= parameter, so that the manipulated image can still be accessible from the browser. For this reason, it is advisable that this parameter not be specified if you are pulling the images from below web root.

default relative path:
/images/made/images/example/cow_square_100_100.jpg

auto_cache relative path:
/images/example/ce_cache/cow_square_100_100.jpg

default relative path:
{exp:ce_img:pair src="/images/example/cow_square.jpg" max="100" auto_cache=""}{made}{/exp:ce_img:pair}

auto_cache relative path:
{exp:ce_img:pair src="/images/example/cow_square.jpg" max="100" auto_cache="ce_cache"}{made}{/exp:ce_img:pair}

aws_auto_url=

The aws_auto_url= parameter determines whether or not the Amazon Web Services (AWS) domain (specified by the bucket= parameter) should be appended. The value for this parameter can be "y" or "n", and the default is "y" (which means the AWS domain will be appended by default).

For example, if s3.causingeffect.com is passed in for the bucket= parameter, it would automatically be turned into s3.causingeffect.com.s3.amazonaws.com. However, if aws_auto_url="no" was set, then the domain would not be appended, and the result would remain s3.causingeffect.com.

In the example below, the first image is auto appending the aws URL, and the second is not.

{exp:ce_img:single src="/images/example/cow_square.jpg" bucket="s3.causingeffect.com" title="Pulled from {aws_url}"}
        {exp:ce_img:single src="/images/example/cow_square.jpg" bucket="s3.causingeffect.com" aws_auto_url='n' title="Pulled from {aws_url}"}

Note: Using a custom AWS domain requires additional configuration on your part, and is beyond the scope of this documentation or CE Image support. To set up a custom AWS domain, pop open your favorite search engine and query "amazon s3 custom domain". ;)

bg_color=

The bg_color= parameter allows you to input a background fill color as a hexadecimal value. Leave blank or not specified for transparency (if a png or gif) or to default to white (if a jpeg). This parameter comes in handy if you want to add a background color or save a transparent png as a different format.

If the manipulated image is very large (2000px by 2000px or greater), you will need to increase your memory limit setting to greater than 64 (Megabytes) in order to avoid memory errors.

In the example below, the png image is saved with a background color of #d6f3ff.

{exp:ce_img:single src="/images/example/cow-sign.png" bg_color="#d6f3ff"}

bg_color_default=

The default background fill color to be used, in the form of a hexadecimal value. By default, PHP will convert transparency to black pixels. So, for example, if you are saving a mostly transparent png image to jpg format, the transparent pixels would end up appearing black. CE Image already changes that default to white (#ffffff), and this parameter allows you to override that default to the color value of your choice.

This parameter is particularly useful if you want to apply filters to a png image that will be saved as a jpg, as it allows you apply the filters to the png image before the background color is applied.

{exp:ce_img:single src="/images/example/cow-sign.png" save_type="jpg" filter="grayscale"}
{exp:ce_img:single src="/images/example/cow-sign.png" save_type="jpg" filter="grayscale" bg_color="#d6f3ff"}
{exp:ce_img:single src="/images/example/cow-sign.png" save_type="jpg" filter="grayscale" bg_color_default="#d6f3ff"}

border=

This parameter allows you to create a solid color border around your image. If you are using this parameter in combination with rounded_corners=, the borders will be antialiased, to give a nice smooth appearance. The general syntax for this parameter is border="thickness|color". The color can be a 3 or 6 digit hexadecimal (with or without the #), and defaults to 'ffffff' if not specified.

Note: Like borders applied with CSS, the border is created on the outer edge of the image (as opposed to an inner border). If you have a 100px by 100px image for example, with a border-width of 10 passed in, your final image dimensions would be 120px by 120px.

{exp:ce_img:single src="/images/example/cow_square.jpg" border="5|4a2d14"}
{exp:ce_img:single src="/images/example/cow_square.jpg" border="5|4a2d14" save_type="png" rounded_corners="tl,50|br,50"}

bucket=

Pass in the name of the Amazon S3 bucket you would like the manipulated image(s) to be saved to.

This parameter works in conjunction with the optional CE Image - AWS extension, please see the installation instructions for more details on how to install the extension.

Note: You should always use EE’s native tag caching when using Amazon S3 with your site (please view the performance page for more details).

{exp:ce_img:single src="/images/example/cow_square.jpg" bucket="causingeffect" cache="yes" refresh="360" title="Pulled from {aws_url}"}

{exp:ce_img:pair src="/images/example/cow_square.jpg" bucket="causingeffect" cache="yes" refresh="360"}
<img src="{aws_url}" alt="" width="{width}" height="{height}" title="Pulled from {aws_url}" />
{/exp:ce_img:pair}

cache_dir=

This parameter allows you to specify a cache directory. If this parameter is not specified, or left blank (""), then the default cache directory will be used. The default cache directory can be specified in the pi.ce_img.php file, by assigning a value to the $cache_dir variable (initially set to '/images/made/').

cache_dir set to "/images/made/" relative path:
/images/made/images/example/cow_square_100_100.jpg

cache_dir set to "/images/test/" relative path:

<p><b>cache_dir set to "/images/made/" relative path:</b><br />
{exp:ce_img:pair src="/images/example/cow_square.jpg" max="100" cache_dir="/images/made/"}{made}{/exp:ce_img:pair}</p>

<p><b>cache_dir set to "/images/test/" relative path:</b><br />
{exp:ce_img:pair src="/images/example/cow_square.jpg" max="100" cache_dir="/images/test/"}{made}{/exp:ce_img:pair}</p>

create_tag=

This parameter allows you to return an image tag without having to type out all of the boilerplate code. This parameter changes depending if you are using the single tag (no tag data) or tag pair (has a closing tag) syntax.

Single Tag Syntax

If you are using a single tag, this value defaults to "yes". The following two plugin calls are identical:

{exp:ce_img:single src="/images/example/cow_square.jpg" create_tag="yes"}
{exp:ce_img:single src="/images/example/cow_square.jpg"}

When the tag is created, the width, height, and a blank alt attribute are automatically set for you. So, the above plugin calls will both return the following HTML:

<img src="/images/example/cow_square.jpg" width="200" height="200" alt="" />

Note: If create_tag is set to "no" for a single tag, nothing will be returned.

Adding Attributes When Using Single Tag Syntax

The width and height attributes will be added to the image tag, along with any attributes you pass in. Here’s an example:

{exp:ce_img:single src="/images/example/cow_square.jpg" id="single_tag_test" class="tester" alt="The Cow" title="An attribute example"}
<img src="/images/example/cow_square.jpg" id="single_tag_test" class="tester" alt="The Cow" title="An attribute example" width="200" height="200" />

Note: Please note that the alt tag is not automatically added if you are passing in attributes, but the width and height attributes are still included.

Pair Tag Syntax

If you are using a pair tag, this value defaults to "no". Here is an example of using pair tag syntax:

{exp:ce_img:pair src="/images/example/cow_square.jpg" create_tag="yes"}
{/exp:ce_img:pair}

When the tag is created, the width, height, and a blank alt attribute are automatically set for you. So, the above plugin call will return the following HTML:

<img src="/images/example/cow_square.jpg" width="200" height="200" alt="" />

Adding Attributes When Using Tag Pair Syntax

There are two ways to add attributes when using tag pair syntax. The first way, like the single tag syntax above, is to pass in the attributes directly to the plugin tag. Additionally you can pass the attributes in as tag data. Here are examples of the two ways to specify attributes using the tag pair syntax:

{exp:ce_img:pair src="/images/example/cow_square.jpg" create_tag="yes" class="something" title="Tag pair attribute" alt="More Cow Bell" style="border: 2px solid #f6861f;"}
{/exp:ce_img:pair}

{exp:ce_img:pair src="/images/example/cow_square.jpg" create_tag="yes"}
class="something" title="Tag pair attribute" alt="More Cow Bell" style="border: 2px solid #f6861f;"
{/exp:ce_img:pair}

The above two plugin calls result in the same HTML:

<img src="/images/example/cow_square.jpg" class="something" title="Tag pair attribute" alt="More Cow Bell" style="border: 2px solid #f6861f;" width="200" height="200" />

crop=

Determines whether the image will just be resized or cropped. If the crop is to take effect, both the width and height parameters (or one of their aliases, including the max parameter) need to be specified (and greater than 0). If you do not want to crop an image, there is no need to add in this parameter, however, you can also leave the value blank ("") or pass in "no" if you feel so inclined.

There are a number of options for this parameter that aim to give you a large degree of control. The general syntax for this parameter is crop="yes_or_no|position|offset|smart_scale". Here’s a look at each of the sub parameters in more detail:

yes_or_no: This sub parameter can have a value of yes or no. As stated previously, if a value of no is passed in, the image will not be cropped.

position: This can be specified as a pair of positions in the form of horizontal_position_string,vertical_position_string. The accepted values for the horizontal position string are: left, center, or right. The accepted values for the vertical position string are: top, center, or bottom. The default is center,center.

offset: The amount of pixels to offset the image after it is positioned in the form offset_x,offset_y, where offset_x and offset_y are integers. An example value for this sub parameter is: -10,40. The default offset is 0,0.

smart_scale: This sub parameter can have a value of yes or no, with the default value being yes. When smart_scale is enabled, the image is scaled to best fit in the specified dimensions. If set to false, the image is not scaled at all. This can also be helpful if you want to focus in on a particular area of an image without scaling it.

Note: Like a CSS background image, if an image is offset too far in one direction, you may see less of it.

In this example, the first image uses the default cropping, and the second image uses the offset sub parameter to home in on the cow’s head.

{exp:ce_img:single src="/images/example/cow.jpg" width="200" height="130" crop="yes"}
{exp:ce_img:single src="/images/example/cow.jpg" width="200" height="130" crop="yes|center,center|0,40"}

This example shows three images that are positioned and offset differently.

{exp:ce_img:single src="/images/example/cow.jpg" width="100" height="200" crop="yes|left,top|-4,0"}
{exp:ce_img:single src="/images/example/cow.jpg" width="100" height="200" crop="yes"}
{exp:ce_img:single src="/images/example/cow.jpg" width="100" height="200" crop="yes|right,top|4,0"}

The following example exhibits the ability to crop, position, and offset images. The image is first cropped by the outer tag pair. The inner single tags crop the image into 9 “slices” and output the results.



{exp:ce_img:pair src="/images/example/cow.jpg" max="300" crop="yes" filter="sharpen,20" parse="inward"}
{exp:ce_img:single src="{made}" max="100" crop="yes|left,top|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|center,top|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|right,top|0,0|no"}
<br />
{exp:ce_img:single src="{made}" max="100" crop="yes|left,center|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|center,center|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|right,center|0,0|no"}
<br />
{exp:ce_img:single src="{made}" max="100" crop="yes|left,bottom|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|center,bottom|0,0|no"}
{exp:ce_img:single src="{made}" max="100" crop="yes|right,bottom|0,0|no"}
{/exp:ce_img:pair}

debug= (Deprecated)

Note: As of version 2.1.4, this parameter has been deprecated and is not longer needed. The plugin will automatically enable debug mode if you are logged in as a Super Admin and have template debugging enabled.

This parameter works in conjunction with the EE template debugger to display error messages (take a look at Debugging for instructions on enabling EE’s template debugger).

debug="yes" For example, if none of your images are not showing up and you have no idea why, you could set this parameter to debug="yes", and you may find out that your cache directory folder does not have write permissions setup correctly. The following error message would appear in the EE template debugging console:

CE Image - Debug: Could not create the cache directory.

If you look at your debug messages, and still cannot figure out what went wrong, check out Troubleshooting.

disable_xss_check=

When you download images from other domains, the plugin can optionally run CodeIgniter®’s XSS filter. Sometimes the filter may flag your image as malicious, even when you know it is not. You can enable this filter if you do not trust the source of the remote images you are downloading (for example, you are manipulating images from a user provided URL). To enable the filter, simply add this to your CE Image tag: disable_xss_check="no".

If your images do not pass the XSS filter, a debug message will be logged in your Template Debugging console like:

CE Image - Debug: Remote image failed XSS test.

Note: You can optionally enable this filter by default for all CE Image tags. See Basic Configuration for more details.

encode_urls=

Essentially, this replaces spaces with %20 so that they validate. This parameter is enabled by default, but can be disabled by setting it to "no".

In the example below, you can see the default behavior to encode the space in the filename, immediately followed by the parameter being disabled.

{exp:ce_img:single src="/images/example/cow square.jpg"}
{exp:ce_img:single src="/images/example/cow square.jpg" encode_urls="no"}

fallback_src=

Sometimes you may want to specify a fallback image. For example, if you are showing thumbnails of the photos for different users on your site, and some of the users are missing photos, you could designate a default photo to replace the missing photos (like one of those unisex silhouette images) via the fallback_src= parameter.

In the example below, the source image does not exist, so the fallback_src is used.

{exp:ce_img:single src="/does/not/exist.jpg" fallback_src="/images/example/cow_square.jpg"}

filename=

The filename you would like the image saved as. By default, the filename of the source image is used.

In the below example, the original image (cow_square.jpg) is saved with a new filename of moo.jpg.

Note: Please note that by default, size, filter, and cropping info will be concatenated to the filename to make sure the cached image is unique (this behavior can be changed using the unique= parameter).

<!-- changed filename to "moo" -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename="moo"}

<!-- changed filename and disabled unique data -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename="moo" unique="none"}
<!-- changed filename to "moo" -->
<img src="/images/made/images/example/moo_200_200.jpg" width="200" height="200" alt="" />

<!-- changed filename and disabled unique data -->
<img src="/images/made/images/example/moo.jpg" width="200" height="200" alt="" />

filename_prefix=

Optionally add a prefix to the filename of the manipulated image.

In the below example, the original image (cow_square.jpg) is prefixed with my_.

<!-- prefixed with "my_" -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename_prefix="my_"}

<!-- prefixed and disabled unique data -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename_prefix="my_" unique="none"}
<!-- prefixed with "my_" -->
<img src="/images/made/images/example/my_cow_square_200_200.jpg" width="200" height="200" alt="" />

<!-- prefixed and disabled unique data -->
<img src="/images/made/images/example/my_cow_square.jpg" width="200" height="200" alt="" />

filename_suffix=

Optionally add a suffix to the filename of the manipulated image.

In the below example, the original image (cow_square.jpg) is concatenated with the suffix _foo.

<!-- suffix with "_foo" -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename_suffix="_foo"}

<!-- suffix and disabled unique data -->
{exp:ce_img:single src="/images/example/cow_square.jpg" filename_suffix="_foo" unique="none"}
<!-- suffix with "_foo" -->
<img src="/images/made/images/example/cow_square_200_200_foo.jpg" width="200" height="200" alt="" />

<!-- suffix and disabled unique data -->
<img src="/images/made/images/example/cow_square_foo.jpg" width="200" height="200" alt="" />

filter=

More than one filter can be applied at a time. Using a filter takes on the form 'filter_name,arg_1,arg_2,arg_3,arg_4', for as many arguments as the respective filter requires, if any (see filters page for more details). Multiple filters are pipe (|) delimited, for example: 'filter_name,arg_1,arg_2,arg_3,arg_4|filter_name,arg_1|filter_name'. Please view the filters page for the available filters and details on their use.

flip=

The flip parameter allows you to flip your image horizontally (x-axis), vertically (y-axis), or both (x and y axes). You can simply pass in one of the following: h, v, h|v, v|h

Note: For reasons unknown, the image quality may be changed when using this parameter (although the difference should not be too noticeable). The below 3 images all result in different file sizes…

Below are some examples of the flip parameter in action.

{exp:ce_img:single src="/images/example/cow_square.jpg"}
{exp:ce_img:single src="/images/example/cow_square.jpg" flip="h"}
{exp:ce_img:single src="/images/example/cow_square.jpg" flip="v|h"}

force_remote=

In rare occasions, you may have a script on your current domain that is serving up the images (from a database or something) rather than using actual image assets on your server. By specifying the fully quantified URI to the image (example: http://www.example.com/image_script.php?id=blah) and using this parameter, CE Image will know to attempt to retrieve the image over http, instead of looking for an actual image asset. The image will then be downloaded to the server and manipulated in the same manner as a remote image.

<img src="/images/example/cow_square.jpg" width="200" height="200" alt="" />
<img src="/images/remote/http_www.causingeffect.com/images/example/cow_square.jpg" width="200" height="200" alt="" />
{exp:ce_img:single src="{path='/images/example/cow_square.jpg'}"}
{exp:ce_img:single src="{path='/images/example/cow_square.jpg'}" force_remote="yes"}

hash_filename=

This parameter allows you to hide the name of the image by using a hash as the final filename, which means your site users will not be able to tell what the original filename was. Possible values are "yes" and "no", with the default being "no".

In the below example, the original image is first saved without hashing the filename (default behavior, resulting in cow_square.jpg) and then again with the filename hashed (resulting in 713685002abfff67fa5972c959739477922dedca.jpg for the filename).

{exp:ce_img:single src="/images/example/cow_square.jpg"}
{exp:ce_img:single src="/images/example/cow_square.jpg" hash_filename="yes"}

height=

The maximum height you would like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero). You can also pass in a percentage of the source image’s height. If a percentage is used, the plugin will convert it to a pixel value and size the image accordingly.

In the first example below, a max height of 100px is specified. Since a max width is not specified, the image’s width is scaled proportionately to the new height (in this case, the width is automatically sized to 67px). For the second example, the image is resized as a percentage of the source image’s height.

If the max= or max_height= parameters are set and have smaller dimensions than this parameter (or the height of the source image), they will override this parameter.

{exp:ce_img:single src="/images/example/cow.jpg" height="100"}
{exp:ce_img:single src="/images/example/cow.jpg" height="3.33%"}

hide_relative_path=

This parameter allows you to hide the relative path of the original file. This can be useful, if you do not want to give away the relative path to the original image. Possible values are "yes" and "no", with the default being "no".

In the below example, the first image shows the relative path (default behavior) (resulting in /images/made/images/example/cow_square_200_200_100.jpg), and the second image has the hide_relative_path option set to yes (resulting in /images/made/cow_square_200_200_100.jpg).

Note: This option essentially places the cached image in the cache directory without creating the sub folders for the relative path. The caveat with this is that it is possible that you could accidentally have more than one file reading/saving to the same cache. Consider, for example, that you have an image at /images/example/cow.jpg and a different image with the same filename located at /other_images/cow.jpg. If you have the hide_relative_path="yes" set for both, they will both be caching to the same directory, and the wrong one may be served up for one of them! A simple workaround for this would be to specify a unique cache_dir for at least one of the images, as they would then be caching to separate locations (and still without revealing their respective original image’s relative path).

{exp:ce_img:single src="/images/example/cow_square.jpg"}
{exp:ce_img:single src="/images/example/cow_square.jpg" hide_relative_path="yes"}

interlace=

This parameter allows you to specify whether or not a generated image will be interlaced. Possible values are "yes" and "no", with the default being "no".

Note: For JPEG images, this is often referred to as “progressive” JPEGs.

{exp:ce_img:single src="/images/example/cow_square.jpg"}
{exp:ce_img:single src="/images/example/cow_square.jpg" interlace="yes"}

manipulate=

The manipulate parameter tells the plugin whether or not you want to manipulate the image. The default is "yes".

Sometimes you may want to get an images info, without the overhead of manipulating it. To do so, simply set this parameter to "no".

There are a number of reasons you may want to get the original image without manipulating it. For example, you want to know the filename, file size, generate ascii_art, get the top_colors, etc.

Any manipulation parameters that are passed into the plugin will be ignored.


Name: cow_square
Size: 38.49 KiB

{exp:ce_img:pair src="/images/example/cow_square.jpg" manipulate="no"}
<p>
<img src="{orig}" alt="" width="{width}" height="{height}" /><br />
Name: {name}<br />
Size: {filesize}
</p>
{/exp:ce_img:pair}

max=

The maximum width and height you would like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero).

This parameter is a shorthand way of setting the max_height= and max_width parameters simultaneously. However, this parameter in turn can be overridden by the max_height= and max_width parameters respectively.

{exp:ce_img:single src="/images/example/cow.jpg" max="100" crop="yes"}
{exp:ce_img:single src="/images/example/cow.jpg" width="100" height="100" crop="yes"}

max_height=

This parameter will ensure that the manipulated image’s height does not exceed its value. It will override both the height= and max= height variables if applicable.

max_width=

This parameter will ensure that the manipulated image’s width does not exceed its value. It will override both the width= and max= width variables if applicable.

min=

The minimum width and height you would like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero).

This parameter is a shorthand way of setting the min_height= and min_width parameters simultaneously. However, this parameter in turn can be overridden by the min_height= and min_width parameters respectively.

Note: Please keep in mind that in order to prevent unintentional image distortion, CE Image will never stretch an image larger than its original (source image) dimensions, unless you set the allow_scale_larger= parameter to "yes".

{exp:ce_img:single src="/images/example/cow.jpg" width="50" height="50" crop="yes"}
{exp:ce_img:single src="/images/example/cow.jpg" width="50" height="50" min="100" crop="yes"}

min_height=

This parameter will ensure that the manipulated image’s height is at least the given value. It will override both the height= and min= height variables if applicable.

Note: Please keep in mind that in order to prevent unintentional image distortion, CE Image will never stretch an image larger than its original (source image) dimensions, unless you set the allow_scale_larger= parameter to "yes".

min_width=

This parameter will ensure that the manipulated image’s width is at least the given value. It will override both the width= and min= width variables if applicable.

Note: Please keep in mind that in order to prevent unintentional image distortion, CE Image will never stretch an image larger than its original (source image) dimensions, unless you set the allow_scale_larger= parameter to "yes".

output=

Sometime you may want to output something other than the image tag. Many times you can simply do this with the tag pair syntax, but you may want to do this from a single tag too. This parameter lets you customize the plugins output.

Note: This parameter will take precedence over the create_tag= parameter, and the tag data inside of the tag pair (if applicable).

Example: Take a look at cow_square_200_200_80.jpg! It’s only 10.64 KiB when the quality is set to 80%, and the original image (cow_square.jpg) is 38.49 KiB.'}

<b>Example</b>: {exp:ce_img:single src="/images/example/cow_square.jpg" quality="80" output='
Take a look at <a href="{made}">{name}.{extension}</a>! It&rsquo;s only {filesize} when the quality is set to 80%, and the original image (<a href="{orig}">{name_orig}.{extension_orig}</a>) is {filesize_orig}.
'}

overwrite_cache=

Overwrites the cached image and will always generate a new image. This will drastically hinder performance if set to "yes", as the image will be created each time the plugin is called. Accepted values are "yes" and "no", and the default is "no".

overwrite_cache="yes"

Note: This will overwrite an image cached by the plugin. If you have ExpressionEngine®’s native tag caching enabled, you will first need to disable it by setting cache="no".

quality=

Sets the quality of a jpg/jpeg file. The quality can range from 0 (lowest) to 100 (highest) and should be a whole number. The default quality is 100.

Note: This parameter has no effect if the final image is a png or a gif, as they are always saved at their respective highest qualities.

You can see in the example below that the quality of the first image is very low (10%), compared to the default quality used in the image on the right (100%). The advantage of setting the quality lower is reduced file size (and ultimately page loading speed). Setting a quality of 80 is often a good way to radically lower file size without drastically affecting the image’s appearance.

{exp:ce_img:single src="/images/example/cow_square.jpg" quality="10"}
{exp:ce_img:single src="/images/example/cow_square.jpg"}

reflection=

The reflection= parameter allows you to create a reflection for the image, otherwise known as the “wet floor effect.” The general syntax for this parameter is reflection="gap_height,start_opacity,end_opacity,reflection_height". Here’s a look at each of the sub parameters in more detail:

gap_height: The vertical space, in pixels, between the image and its reflection.

start_opacity: The opacity of the reflection at the top of the reflection. This can be any number between 0 (completely transparent) and 100 (completely opaque). The default is 80.

end_opacity: The opacity of the reflection at the bottom of the reflection. This can be any number between 0 (completely transparent) and 100 (completely opaque). The default is 0.

reflection_height: The height of the reflection, either in pixels, or as the percentage of the image. If specifying as a percentage, then a % should be concatenated on the end. For example, if the made image was 100px tall, and a reflection height of 50% was specified, then the resulting reflection would be 50px tall.

The default settings are: reflection="0,80,0,50%".

{exp:ce_img:single src="/images/example/cow_square.jpg" reflection="10,100,0,50%" save_type="png"}
{exp:ce_img:single src="/images/example/cow_square.jpg" reflection="0,80,0,110" bg_color="f0f0f0"}
{exp:ce_img:single src="/images/example/cow-sign.png" reflection="10"}

remote_cache_time=

This parameter allows you to override the minimum specified interval a remote image should be cached before having to re-download the image. The default is '-1', which means CE Image will never attempt to re-download the image. The default can be changed globally by assigning a value to the $remote_cache_time variable in pi.ce_img.php, but can be overridden in config.php, and authoritatively overridden by this parameter.

If you have the PHP Curl extension enabled and the remote_cache_time is set to 0, the plugin will attempt to retrieve the last modified date of the remote image. If you set the cache time to 0 (meaning you want the plugin to check remote images for a newer version), then you should always use EE’s native tag caching or another caching alternative (please view the performance section for more details)!

If the remote time is not set to 0, the plugin will wait the specified amount of minutes before re-downloading the image. If you prefer that the plugin never attempts to check if the remote image has changed, or to download a newer version, then please set this value to -1 (remember this can also be set in the config.php file or the plugin itself).

The below example would cache a remote image for a minimum of 1440 minutes (24 hours), before re-downloading the image:

remote_cache_time="1440"

remote_dir=

PHP can only manipulate images that are on the local server. So if an image is located on another server, it must first be downloaded to your server before it is manipulated. This parameter allows you to specify a cache directory for the downloaded remote images. The downloaded image will then be used to manipulate and cache your final image, using the same parameters as a default image on your site.

If this parameter is not specified, or left blank (''), then the default remote cache directory will be used. The default remote cache directory can be specified in the pi.ce_img.php file, by assigning a value to the $remote_dir variable (initially set to '/images/remote/').

Example:

remote_dir="/images/a_different_directory/"

rotate=

The rotate parameter allows you to rotate an image. Simply pass in a number representing the degrees you would like to rotate the image. Rotated images will appear best when rotated in 90° increments, as PHP does not antialias the edges. The bg_color parameter can be used to specify the background color of space revealed by rotating the image. PHP’s native imagerotate function is used to rotate the image, which unfortunately has poor transparency support.

Note: Images will first be cropped/resized to the dimensions specified, and then rotation will be applied. The rotation of the image may cause the size of the resulting image dimensions to change! For example, if you rotate a portrait image 90°, the width and height dimensions would be effectively swapped. The width and height variables will represent the respective dimensions of the final image.

Note: Images being saved to png format will attempt to create transparent backgrounds for the space revealed by the rotation if no background color is set via the bg_color= parameter, however, transparency only seems to be supported by the more recent versions of PHP 5. If you are getting black backgrounds instead of transparency, you can set a background color via the bg_color= parameter to be used instead. Transparency for images being saved to the gif format does not appear to be supported in any version of PHP 5 that we tested, although you can specify a background color via the bg_color= parameter.

Below are some rotation examples:

{exp:ce_img:single src="/images/example/cow_square.jpg"}

{exp:ce_img:single src="/images/example/cow_square.jpg" rotate="180" bg_color="f0f0f0"}

{exp:ce_img:single src="/images/example/cow_square.jpg" rotate="270" bg_color="f0f0f0"}

{exp:ce_img:single src="/images/example/cow_square.jpg" rotate="436" save_type="png"}

{exp:ce_img:single src="/images/example/cow_square.jpg" rotate="-196" bg_color="f0f0f0"}

rounded_corners=

The rounded_corners parameter allows you to round one or more corners to a certain radius with antialiasing. If you are saving to png format, you can also have the corners be completely transparent. Rounded corners are applied after all resizing, filters, and watermarking has been completed.

There are a number of options for this parameter that empower you with a great deal of control. The general syntax for this parameter is rounded_corners="corner_identifier,radius,color". You can specify any number of comma separated corners, each with their own radius and color information. Corners specified later take precedence over previously specified ones. Here’s a look at each of the sub parameters in more detail:

corner_identifier: This sub parameter can have a value of any one of the following: all, tl, tr, bl, br. If all is used, it will set the preferences for each of the corners.

radius: The radius of the corner. If this is set to 0, the corner will not be rounded. This value defaults to 15 if not specified.

color: Can be left blank to indicate transparency or can be set to 3 or 6 digit hexadecimal number (with or without the #). If the image is being saved as a jpg, the bg_color= will be used as the background color (since the jpg image format does not support transparency).

Note: Transparency for rounded corners is not supported for images being saved to the gif format. If a color is not specified, there will not be a noticeable difference to the image. You can, however, specify opaque colors.

Below are some examples of the flexibility of the rounded_corners= parameter. Some of the effects are extreme just to illustrate the parameters capabilities:

{!-- all 4 corners, default radius (15px), jpg with bg_color --}
{exp:ce_img:single src="/images/example/cow_square.jpg" rounded_corners="all" bg_color="f0f0f0"}

{!-- 1 corner, png --}
{exp:ce_img:single src="/images/example/cow_square.jpg" save_type="png" rounded_corners="bl,100"}

{!-- 2 corners, png --}
{exp:ce_img:single src="/images/example/cow_square.jpg" save_type="png" rounded_corners="all,50|tr,0|bl,0"}

{!-- 3 corners, png --}
{exp:ce_img:single src="/images/example/cow_square.jpg" save_type="png" rounded_corners="all,60|tl,0"}

{!-- 4 equal corners, jpg --}
{exp:ce_img:single src="/images/example/cow_square.jpg" save_type="png" rounded_corners="tr,100,be0b03|br,100,eacd12|bl,100,f0f0f0|tl,100,4491d4"}

{!-- 4 unequal corners colored, jpg --}
{exp:ce_img:single src="/images/example/cow_square.jpg" rounded_corners="tr,100,be0b03|br,150,eacd12|bl,200,1c9a3c|tl,50,4491d4"}

save_type=

The image type you would like to save the image as. You can easily convert an image of one type to a different image type by specifying this parameter. Simply do not include this parameter or leave the parameter blank ("") to save as the image type of the original image, or specify the save type as one of the following: png, jpg, jpeg, gif

In the example below, the first image is a jpg being saved as a png, and the second image is a png being saved as a gif (notice the chunky gif look).

{exp:ce_img:single src="/images/example/cow_square.jpg" save_type="png"}
{exp:ce_img:single src="/images/example/cow-sign.png" save_type="gif"}

src=

This is the path to your image, and can be: a full server path, a relative path to your web root directory, a URL, an external URL, or HTML.

The source can be a relative path:

src="/images/example/cow.jpg"
src="images/example/cow.jpg"
src="./../../directory_above_web_root/blah.jpg"

A URL:

src="http://www.your_current_domain.com/images/example/cow.jpg"

An external URL:

src="http://www.an_external_domain.com/blah/example.jpg"

A full server path:

src="/var/www/vhosts/example.com/httpdocs/images/example/cow.jpg"

Or HTML:

src='<p>Some HTML. An image: <img src="/images/example/cow.jpg" alt="" /></p>'

If HTML is passed in, the plugin will attempt to use the src= attribute of the first found image tag. If you are planning on using HTML, it should be minimal, like just an image tag. Additionally, you will most likely need to wrap the value in single quotes, as opposed to double quotes.

text=

Enables text to be added to the manipulated image.

The syntax for this parameter takes the form:
text="the_text,​minimum_dimensions,​font_size,​line_height,​font_color,​font_src,​text_align,​width_adjustment,​position,​offset,​opacity,​shadow_color,​shadow_offset,​shadow_opacity". Here’s a look at each of the sub parameters in more detail:

the_text: The text to add to the image. HTML entities will automatically be converted to their text equivalents.

minimum_dimensions: This is a pair of comma separated integers that specify the minimum width and height dimensions needed for the text to appear. The default for this sub-parameter is 0,0 (representing minimum_width,minimum_height respectively). Setting a dimensions to 0 (zero) means that there is no minimum (since the default is 0,0, the text will always appear). If the manipulated image has dimensions that are less than one or both of the dimensions specified, and are not set to zero, then the text will not appear.

font_size: The text font size. The default is 12.

line_height: The line height. This can be an integer (to specify the pixel value, eg: 15), or a percentage of the font_size (eg: 120%). The default is 125%. Similar to CSS, this value can be used to set the text leading.

font_color: The text color. Can be a 3 or 6 digit hexadecimal number (with or without the #). The default is #ffffff.

font_src: The font file to use for the font. This can be a full server path, the font filename if the font is in the system/expressionengine/third_party/ce_img/fonts/ directory, or a relative path to your web root directory. If the specified font cannot be found, or if none is provided, then the default font heros-bold.ttf will be used. You can download 33 open source .ttf fonts for use in your site from here.

text_align: The way the text should align. The options are: left, center, or right. The default is center.

width_adjustment: An integer to adjust the width by. By default, the line width for the text will be the manipulated image’s width. You may, however, want to adjust the width. For example, if the image’s width is 160px, but you only want the line width to be 140px, you would specify a value of -20. The default value is 0.

position: This parameter will position the block of text in relation to the image. This can be specified as a pair of positions in the form of horizontal_position_string,vertical_position_string. The accepted values for the horizontal position string are: left, center, or right. The accepted values for the vertical position string are: top, center, or bottom. The default position pair is center,center.

offset: The offset of the text after it is positioned in the form offset_x,offset_y. For example, if right,bottom is specified for the position, you may want to provide an offset of -10,-10 to move the text 10px to the left and 10px up so the text is not placed so snug to the edges. The default offset is 0,0.

opacity: The transparency of the text, ranging from 0 (completely transparent) to 100 (completely opaque). Defaults to 100.

shadow_color: The shadow text color. Can be a 3 or 6 digit hexadecimal number (with or without the #). The default is #000000. If not specified to a valid hexadecimal color value, the shadow text will not be applied.

shadow_offset: The offset of the shadow text (in pixels), in the form shadow_offset_x,shadow_offset_y. The default shadow offset is 1,1.

shadow_opacity: The transparency of the shadow text, ranging from 0 (completely transparent) to 100 (completely opaque). Defaults to 50.

text="This is a picture of a cow"

Although there are many sub parameters for this parameter, you don’t have to enter each one every time. You can simply leave a sub-parameter blank to have it use the default value.

{exp:ce_img:single src="/images/example/cow_square.jpg" text="These are cows"}

{exp:ce_img:single src="/images/example/cow_square.jpg" text="These cows eat grass.|200,200|12|125%|#000|heros-bold.ttf|left|-150|left,center|10,20|100|fff|-4,-4|80"}

{exp:ce_img:single src="/images/example/cow_square.jpg" text="&ldquo;Cows&rdquo;|||||heros-bold.ttf||-20|center,bottom|0,-10||#000||50"}

To specify different text for different dimensions, you can separate your preferences by a double hash sign (##). CE Image will determine which preference to use depending on the size of your manipulated image. Here’s an example:

{exp:ce_img:single src="/images/example/cow_square.jpg" text="Copyright 2011|200,200|||||||center,bottom|0,-10|80|-##&copy; 2011|100,100|10||||||center,bottom|0,-5|80|-"}

{exp:ce_img:single src="/images/example/cow_square.jpg" text="Copyright 2011|200,200|||||||center,bottom|0,-10|80|-##&copy; 2011|100,100|10||||||center,bottom|0,-5|80|-" max="100"}

top_colors=

This parameter will organize the colors used in your image by frequency, and allow you to group them to a certain threshold. The general syntax for this parameter is top_colors="number_of_color_groups_to_return|threshold". Here are more details for these sub parameters:

number_of_color_groups_to_return: This sub parameter allows you to specify the maximum number of colors you would like to be returned. Colors are grouped depending on the threshold you provide for the second sub parameter. This is useful because instead of returning thousands of colors individually, similar colors are grouped and their average hexadecimal color value is returned.

threshold: This sub parameter can be any value from 0 (very low grouping) to 100 (very high grouping). If no threshold is specified, it will default to 33.

To access the colors, you use the {top_colors}{/top_colors} tag pair. Inside the tag pair, the following two variables are available: {color} (which is the averaged hex color value of the returned color group) and {color_percent} which is a rough estimate of the percentage of the image that the color group represents. Here is what the code for this looks like:

{exp:ce_img:pair src="{your_custom_field}" top_colors="10"}
{if top_colors}
{top_colors}
<p style="color:{color};">{color} - {color_percent}%</p>
{/top_colors}
{/if}
{/exp:ce_img:pair}

Note: Since this parameter has additional tags that need to be parsed, it should not be used with the `create_tag="yes"` parameter.

Note: The color values of completely transparent pixels are ignored.

Note: The top_colors results are not cached. You can, however, cache the results via ExpressionEngine®’s native tag caching. You may also want to check out the performance page.

The following two examples illustrate how color palettes can be generated for an image:

Here is a sample color palette for this image:

#cad6f2 (≈ 26.4%)

#39200e (≈ 15.3%)

#6a3917 (≈ 10.9%)

#c9843c (≈ 10.6%)

#a2b9ec (≈ 8.9%)

#877832 (≈ 7.4%)

#d7ba70 (≈ 6.2%)

#dae6fc (≈ 5.4%)

#b2b44b (≈ 2.7%)

#ca9c66 (≈ 2.6%)


Here is a sample color palette for this image:

#030300 (≈ 63.6%)

#ffd51d (≈ 30.5%)

#e0ba19 (≈ 2.5%)


{!-- Cow top_colors= example --}
{exp:ce_img:pair src="/images/example/cow_square.jpg" top_colors="10"}
<p style="float: left;" ><img src="{made}" alt="" width="{width}" height="{height}" /></p>
{if top_colors}
<div style="float: left; margin-left: 15px;">
Here is a sample color palette for this image:

{top_colors}
<p style="margin-bottom: 0;"><span style="display:block; float:left; width:1em; height:1em; background-color:{color}; margin-right: 10px"><!-- --></span>{color} (&asymp; {color_percent}%)</p>
{/top_colors}
</div>
{/if}
{/exp:ce_img:pair}

{!-- sign top_colors= example --}
{exp:ce_img:pair src="/images/example/cow-sign.png" top_colors="10"}
<p style="float: left;" ><img src="{made}" alt="" width="{width}" height="{height}" /></p>
{if top_colors}
<div style="float: left; margin-left: 15px;">
Here is a sample color palette for this image:

{top_colors}
{if '{color_percent}' > 2}
<p style="margin-bottom: 0;"><span style="display:block; float:left; width:1em; height:1em; background-color:{color}; margin-right: 10px"><!-- --></span>{color} (&asymp; {color_percent}%)</p>
{/if}
{/top_colors}
</div>
{/if}
{/exp:ce_img:pair}

unique=

When an image is manipulated, a string is generated that reflects the actions that were done to the image. This string is used to ensure the manipulated image is cached to a unique file for the actions that were applied to it. The options for the plugin are "filename", "directory_name", and "none".

The "filename" option is default, and means the unique string will be added to the filename.

unique="filename"

The "directory_name" option creates a folder using the string, and places the manipulated image (with the original filename), inside the folder, thereby preserving the image name.

unique="directory_name"

And finally, the "none" option will not change the filename or create a special folder. Setting this parameter to "none", is not recommended, as it increases the risk of different manipulations of the same image being cached to the same file, causing unexpected results.

unique="none"

url_only=

This parameter simply returns the relative URL for the image. This can be very useful in certain situations.

This parameter is equivalent to: output="{made}". For more customized output hijacking, check out the output= parameter.

url_only="yes"

watermark=

Enables a watermark to be added to the manipulated image.

The syntax for this parameter is in the form: watermark="watermark_src|minimum_dimensions|opacity|position|offset|blend". Let’s take a closer look at the watermark sub parameters:

watermark_src: This is a relative path to the image to be used as the watermark.

minimum_dimensions: This is a pair of comma separated integers that specify the minimum width and height dimensions needed for this watermark to appear. The default for this sub-parameter is 0,0 (representing minimum_width,minimum_height respectively). Setting a dimensions to 0 (zero) means that there is no minimum (since the default is 0,0, the watermark will always appear). If the manipulated image has dimensions that are less than one or both of the dimensions specified, and are not set to zero, then the watermark will not appear.

opacity: The transparency of the watermark, ranging from 0 (completely transparent) to 100 (completely opaque).

position: This allows you to specify the position of the watermark. There are two ways to do this:

  • standard: This can be specified as a pair of positions in the form of horizontal_position_string,vertical_position_string. The accepted values for the horizontal position string are: left, center, or right. The accepted values for the vertical position string are: top, center, or bottom. The default position pair is center,center.
  • repeat: This can be specified as repeat,row_offset_percentage, where row_offset_percentage is a number between 0 and 100 that represents the percentage of the offset of the row, in relation to the previous row. If you don’t include the row_offset_percentage and simply use repeat, a default row_offset_percentage of 50 will be used. The watermark will simply tile, with every other row offset by the specified percentage (which defaults to 50% if no offset is provided).

offset: The offset of the watermark after it is positioned in the form offset_x,offset_y. For example, if right,bottom is specified for the position, you may want to provide an offset of -10,-10 to move the watermark 10px to the left and 10px up so the watermark is not placed so snug to the edges. The default offset is 0,0.

blend: The blend mode affords you the ability to blend the watermark with the image. Currently, there is only one blend mode: multiply. If this option is not specified, or left blank, then no blend mode will be applied.


This is a simple example of a watermark:

{exp:ce_img:single src="/images/example/cow_square.jpg" watermark="/images/watermarks/logo_sm2.png|140,60|80|right,bottom|-10,-10"}


The following is a blend mode example. The first image has not been manipulated, the second image has the sobel_edgify filter applied, and the third image uses the second image as a watermark for the first image with the multiply blend mode applied.

{exp:ce_img:single src="/images/example/cow_square.jpg" manipulate="no"}
{exp:ce_img:single src="/images/example/cow_square.jpg" filter="sobel_edgify,60,000,fff|opacity,80"}
{exp:ce_img:pair src="/images/example/cow_square.jpg" parse="inward" filter="sobel_edgify,60,000,fff|opacity,80"}
{exp:ce_img:single src="/images/example/cow_square.jpg" watermark="{made}|0,0|100|||multiply" parse="inward"}
{/exp:ce_img:pair}


This example shows tiling a watermark image and applying a multiply blend mode to it. The first one shows a repeating pattern watermark (at 75% opacity) without a blend mode and the second shows the same pattern watermark (also at 75% opacity) with the multiply blend mode applied.

{exp:ce_img:single src="/images/example/cow_square.jpg" watermark="/images/watermarks/plaid.png|0,0|75|repeat,0"}
{exp:ce_img:single src="/images/example/cow_square.jpg" watermark="/images/watermarks/plaid.png|0,0|75|repeat,0||multiply"}


One of the inherit difficulties of using dynamic watermarks is ensuring that the size of the final image is not too small for the watermark. This can be especially problematic if the images are submitted by users or clients that are not tech savvy. The minimum_dimensions sub parameter helps to mitigate this problem, however “all or nothin’” didn’t seem good enough, so we added the ability to waterfall watermarks for different dimensions. You can pass in multiple configuration options delimited by a #(hash mark). The first configuration option that meets the dimension limitations will be used.

Here is an example of what we like to call “the watermark waterfall.” As you can see below, multiple watermark settings can be specified for various sizes. The first watermark configuration that works for the dimensions is used.

{exp:ce_img:pair src="/images/example/cow.jpg" max="550" crop="yes" watermark="/images/watermarks/logo_lg1.png|420,520|50#/images/watermarks/logo_sm2.png|310,310|80|right,bottom|-10,-10#/images/watermarks/logo_sm2.png|300,300|30|repeat|30,30#/images/watermarks/logo_sm1.png|0,0|20|repeat|5,5"}
<img src="{made}" alt="" width="{width}" height="{height}" />
{/exp:ce_img:pair}

max="400"

max="300"

max="200"

width=

The maximum width you like the image to be constrained to. Should be a whole number, "" (blank), or 0 (zero). You can also pass in a percentage of the source image’s width. If a percentage is used, the plugin will convert it to a pixel value and size the image accordingly.

In the first example below, a max width of 100px is specified. Since a max height is not specified, the image’s height is scaled proportionately to the new width (in this case, the height is automatically made to 149px). For the second example, the image is resized as a percentage of the source image’s width. If the max= or max_width= parameters are set and have smaller dimensions than this parameter (or the width of the source image), they will override this parameter.

{exp:ce_img:single src="/images/example/cow.jpg" width="100"}
{exp:ce_img:single src="/images/example/cow.jpg" width="5%"}