ParametersLast updated: 12 November 2025

Usage Notes

If you also choose options that will cause the JCOGS Image Pro to generate an HTML <img> tag, this parameter will determine whether the HTML img dimension parameters (width= and height=) will be included in the tag.

Usage Notes

If both add_dims and add_dimensions parameters are specified in the same tag, the value of add_dims will be used.

Usage Notes

Only applies to resize operations. Ignored otherwise.

If the parameter is set to no and other operations specified can be completed without enlarging the image then this parameter will have no effect. 

If the parameter is set to no and any of the other operations specified would require the size of the image to be increased for the operation to complete, these other operations are not applied.

The default value for this parameter is no, but this can be adjusted to default to yes via a control panel setting.

Usage Notes

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

Usage Notes

It is possible to end up in a situation where you have specified content for the attributes parameter in more than one place - for example by specifying an attributes= parameter in a tag-pair, including unrecognised parameters within the JCOGS Image Pro tag, and / or including additional parameters within the content enclosed by the tag-pair.  

When this happens, JCOGS Image Pro simply combines the content of all the sources found, but also intelligently combines any  class= and style= elements so that only one of each is included in the resulting output.

Usage Notes

If other filter values are specified in the same tag, and those other filters include auto_sharpen, then adding this parameter to the tag will have no effect.

If other filter values are specified but those other filters do not include auto_sharpen, then adding this parameter to the tag will cause the auto_sharpen filter to be applied after those other filters have been applied.

Usage Notes

Note: Background colour is applied only to images that end up with no transparency - if an image is in a format that supports transparency then transformations that would cause the background to show are completed using a transparent fill. To apply a background colour to an image that has transparency (e.g. a PNG) simply change its format to one that does not support transparency (e.g. a JPEG).

Usage Notes

Note: Border increases image dimensions

The border is added to the outer edge of the processed image, so the final image dimensions will be increased by twice the border width in each dimension. For example, a 300×200px image with a 10px border becomes 320×220px (300 + 2×10 by 200 + 2×10).

This is particularly important when sizing images for specific layouts or containers - you may need to account for the border width in your dimension calculations.

Usage Notes

Note: Non-rectangular images and transparency

For non-rectangular images (after applying operations like rounded_corners, mask, or shape transformations), the border is drawn relative to the resulting shape, not the rectangular bounding box.

To preserve transparency around borders on non-rectangular images, you must save the image as PNG or WebP format using the format or save_type parameter. JPEG format does not support transparency.

Usage Notes

Performance considerations

For rectangular images without shape transformations, border application is fast and adds negligible processing time (typically <1ms).

For non-rectangular images (after masking, rounded corners, etc.), border application requires more complex calculations and can add 5-15ms to processing time depending on image size and complexity. Ensure these images are properly cached for optimal performance.

Usage Notes

Backward compatibility with legacy format

Both the legacy position-dependent format (border="width|color") and the new named attributes format (border="width:value|color:value") work identically in JCOGS Image Pro. The named attributes format provides better readability and allows attributes to be specified in any order.

Existing templates using the legacy format will continue to work without modification.

Usage Notes

CSS color name support

JCOGS Image Pro recognizes over 140 CSS color names including: red, blue, green, yellow, orange, purple, pink, brown, gray, black, white, cyan, magenta, lime, navy, teal, olive, maroon, aqua, fuchsia, silver, and many more including modern colors like rebeccapurple.

Color names are case-insensitive. Multi-word colors use no spaces (e.g., lightblue, darkgreen, mediumseagreen).

Usage Notes

If the folder specified does not exist, JCOGS Image Pro will try to create it; if that activity fails the tag processing will stop.

The value can be specified with or without a trailing slash.

Usage Notes

Connection vs direct URLs

Named connections offer several advantages over direct URLs:

Without connection (direct URL):

src="https://s3.amazonaws.com/my-bucket/products/image.jpg"

• Exposes storage infrastructure details in templates
• Credentials or access patterns visible in code
• Difficult to migrate storage providers (URL changes everywhere)
• No centralized connection management

With connection (named reference):

src="products/image.jpg" connection="s3_bucket"

• Abstracts storage details from template code
• Credentials managed securely in configuration
• Easy storage provider migration (change connection config, not templates)
• Centralized connection configuration and monitoring

Usage Notes

Supported adapter types

JCOGS Image Pro supports multiple storage adapter types:

Local Filesystem:

• Type: local
• Use case: Alternative local directories, network-mounted storage
• Configuration: Base path, permissions

AWS S3:

• Type: s3
• Use case: Amazon S3 buckets, S3-compatible storage (DigitalOcean Spaces, Cloudflare R2)
• Configuration: Bucket, region, credentials, endpoint (for S3-compatible)

Additional adapters may be available in future via companion add-ons.

Usage Notes

Performance considerations

Connection type affects image processing performance:

Local connections:

• Fastest access (direct filesystem reads)
• Minimal latency (~1-5ms typical)
• Best for high-traffic, performance-critical applications

Remote connections (S3):

• Network latency added (50-200ms typical depending on region)
• First request slower, cached requests fast
• Bandwidth considerations for large images
• Excellent for storage cost optimization and scalability

Optimization strategies:

• Use aggressive caching (cache=-1 for perpetual) with remote connections
• Consider cache warming for high-traffic images
• Store frequently-accessed originals locally, archive less-used images remotely
• Use local cache with remote source for best performance balance

Usage Notes

Debug information

Use debug="yes" to troubleshoot connection issues:

src="photo.jpg" connection="s3_bucket" width="600" debug="yes"

Debug output includes:

• Connection name used
• Adapter type (local, s3, etc.)
• Connection resolution time
• Source file fetch time
• Any connection errors or warnings
• Fallback behavior (if triggered)

Usage Notes

Migration and testing

When migrating storage providers or testing connections:

1. Create new connection: Define test connection alongside production connection
2. Test in development: Use test connection in dev/staging environment
3. Parallel operation: Run both connections simultaneously during transition
4. Switch connection name: Update connection config without changing templates
5. Retire old connection: Remove old connection after successful migration

Example workflow:

• Templates use: connection="primary_storage"
• "primary_storage" initially points to old connection
• Reconfigure "primary_storage" to point to new connection
• Templates unchanged, now use new connection

Usage Notes

Channel field integration

Connections integrate seamlessly with ExpressionEngine channel fields:

File field with connection reference:

src="{cf_product_image}" connection="user_uploads"

The connection name can be:

• Hardcoded in template (as shown above)
• Stored in channel field custom settings
• Determined programmatically via extension hook

Per-channel storage locations:

Different channels can use different connections for organizational clarity:

• Product images: connection="product_storage"
• User avatars: connection="user_content"
• Blog images: connection="blog_media"

This maintains logical separation and enables independent storage management per content type.

Usage Notes

If create_tag="no" is specified for a single JCOGS Image Pro tag, the image specified will be processed by the tag but no output will be returned to the template.

This option can be useful when debugging a template: if JCOGS Image Pro debugging is turned on, when Image processes a tag, the image processing steps will all be carried out and the add-on will generate debugging reports in the template debug log - the only difference being that no output is added to the template output; this approach can sometimes help you track down issues with your templates and Image tags more easily.

Usage Notes

Note: A crop must always be smaller than the original image

If you set the size of your crop to be larger than the source image, JCOGS Image Pro does not know what to do - there are multiple factors that Image does not know how to resolve; accordingly rather than do something and hope it is correct, it simply does not apply the crop and writes a warning into the debug report for the template concerned.

If you want the result of the crop to be proportionately larger than the source, simply nest two tags - one to do the crop, the second to change the image size.

Usage Notes

Tips for adjusting face detection sensitivity

Face detection requires a trade-off to be made between speed and effectiveness. Each image will have its own characteristic - in some face detection will work quickly and easily, on others face detection will require more processing work to be done before the face(s) are found. In some pictures the faces may not be detected at all.

In general face detection is more easily completed where:

• the each of the face(s) to be detected form a large part (> 20% by area) of the image to be processed;
• the background to the face(s) is relatively uncomplicated (e.g. a plain colour);
• the face(s) are front-on views without obstructing / overlapping shapes (e.g. hats, veils etc) and not heavily rotated from the vertical.

JCOGS Image Pro allows you to adjust the amount of processing effort allocated to detect faces via the face_detect_quality parameter.

JCOGS Image Pro includes significantly improved face detection with three quality modes: - fast - Speed priority - balanced - Default, good compromise - thorough - Accuracy priority.

JCOGS Image Pro's face detection is more reliable than original JCOGS Image's version across varied lighting and angles.

One visual way to work out the minimum face detection sensitivity value to use is to apply the face_detect filter to the same image - this filter simply draws a box around any faces it detects in an image, and uses the same face detection algorithm used by crop; if no faces are found, no overlay box is drawn. So apply this filter to the image that you will wish to use with crop find the lowest value for face_detect_sensitivity that delivers an overlay box, and then use this value for the crop.

Usage Notes

Smart scale and face detect crops can be used together

If smart scale  is enabled (the default) and the crop type is set to face detect then the image will be smart-scaled using width / height information provided in the parameter tag before face detection cropping is processed. Face detection will be used to centre the crop on the cropped dimension to be centered on any found face(s) - if no faces are found the crop focus will be center.

Usage Notes

Note:JCOGS Image Pro Dimensions

Throughout JCOGS Image Pro, dimensions 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 or height as appropriate.

Usage Notes

Note on privacy / personal information:

The transformation uses an algorithm to undertake facial detection - the algorithm detects of face-like elements in an image. It does not have the capability to carry out facial recognition, and no information is captured during its operation which would facilitate the identification of the faces found in the images processed.

Usage Notes

Note on the method used:

The face detection parameter uses a modified version of a fairly old but effective algorithm called Viola-Jones / Lienhart object detection which works by looking for characteristic patterns (called Haar features) that appear on faces, and if it finds enough in a given area to suggest that it has found a face it then works out roughly where the edge of the 'face' is, and moves on to process the rest of the image.

Changing the value for “sensitivity” adjusts the size of the blocks used to identify facial features - a higher sensitivity gives a the smaller the block. The smaller the block used the more processing needs to be done to scan an image, but possibly the facial recognition activity will be more effective (i.e. find more and / or smaller faces). However if the sensitivity is set too high (too small a block size) then it is possible that some (larger) faces will be missed, and / or non-facial elements will be falsely identified as faces. So simply putting sensitivity to the max will not necessarily produce better results.

The algorithm used is generally less effective when scanning for faces that are partly occluded, or partly rotated, or faces that placed on highly complex backgrounds.

Usage Notes

Performance impact

Important: Debug mode adds processing overhead (typically 10-30ms) due to additional logging operations and message formatting. Always disable debug mode in production environments unless actively troubleshooting a specific issue.

Usage Notes

Output visibility

Debug output visibility is controlled by JCOGS Image security settings:

• Super Admins only - Default behavior. Debug messages visible only to logged-in Super Admin users.
• All logged-in users - If configured, debug output visible to any authenticated user.
• Public visibility - Generally not recommended. Debug output visible to all visitors if security settings allow.

Output format may be HTML comments, visible text, or logged to ExpressionEngine's developer log depending on configuration.

Usage Notes

Common troubleshooting scenarios

Image not displaying: Enable debug to see if source image is found, if cache lookup succeeds, and where processing fails.

SVG files not working: Debug shows SVG detection, sanitization results, dimension calculation method (TYPE_NONE, TYPE_ASPECT_RATIO, TYPE_FIXED), and any Imagine SVG library errors.

Cache issues: Verify cache keys are generated correctly, cache hits are occurring as expected, and cache file paths are accessible.

Slow processing: Timing information reveals which stages consume most processing time, helping identify bottlenecks.

Remote images failing: Shows connection attempts, HTTP status codes, redirect handling, and download errors.

Usage Notes

Debug output in templates

Debug messages appear near the generated image tag. When using JCOGS Image within loops or conditionals, each iteration generates separate debug output. To reduce noise, enable debug only for specific problematic images rather than all images in a loop.

Example selective debugging within loop:

{exp:channel:entries channel="gallery"}
    {gallery_images}
        {exp:jcogs_img_pro:single
            src="{url}"
            width="300"
            debug="{if url == 'problematic-image.jpg'}yes{/if}"
        }
    {/gallery_images}
{/exp:channel:entries}

Usage Notes

Debug mode and caching

Debug output is generated during image processing, not retrieved from cache. This means:

• Cache hits - Debug shows "using cached copy" message and skips processing stages
• Cache misses - Debug shows complete processing pipeline including all transformation stages
• Cached images - Debug mode does not affect cached image files themselves, only diagnostic output generation

To debug initial processing (not cache retrieval), clear cache first or use unique parameters to force fresh processing.

Usage Notes

Changes for Image Pro

JCOGS Image Pro provides enhanced debug output compared to legacy version:

• Pipeline stages - Pro shows discrete pipeline stage execution (Initialize → Cache Check → Load → Process → Save → Output)
• Service layer visibility - Debug messages from ValidationService, FilesystemService, CacheManagementService included
• Context tracking - Processing context flags tracked (early_cache_hit, using_cache_copy, etc.)
• Preset resolution - Shows preset loading and parameter inheritance when using preset parameter

Usage Notes

Choosing the right quality mode

Select your quality mode based on use case:

Use FAST when:

• Processing large volumes of images (batch operations)
• Speed is more important than perfect accuracy
• Generating thumbnails or small images
• Faces are likely centered and prominent in images
• Real-time or user-facing processing with time constraints

Use BALANCED when:

• Standard content management scenarios
• Good mix of speed and accuracy needed
• Most general-purpose applications
• Default recommendation for production sites

Use ACCURATE when:

• Professional photography or portfolio sites
• Accuracy is critical to user experience
• Processing time is acceptable trade-off
• Small, partial, or difficult faces need detection
• Critical applications where missed faces are unacceptable

Usage Notes

Performance comparison

Benchmark results for face detection on typical portrait images (average 3000×4000px):

Volume recommendations:

• < 10 images: Use accurate (quality over speed)
• 10-100 images: Use balanced (best overall trade-off)
• > 100 images: Use fast (speed critical for large batches)

Usage Notes

Caching behavior

Face detection results are cached along with the processed image:

1. First request: Face detection runs at specified quality level, results cached with image
2. Subsequent requests: Cached image returned instantly (no re-detection needed)
3. Cache invalidation: Changing quality mode or other parameters regenerates cache

Cache key impact: The quality mode is included in the cache key, so different quality modes produce different cached images:

• cache/portrait_400x400_face-detect-fast_abc123.jpg
• cache/portrait_400x400_face-detect-balanced_def456.jpg
• cache/portrait_400x400_face-detect-accurate_ghi789.jpg

This ensures changing quality settings doesn't serve incorrect cached versions.

Usage Notes

When face detection fails

If no faces are detected (regardless of quality mode), the system falls back gracefully:

1. Center crop (if dimensions specified via width/height parameters)
2. Smart crop based on image content analysis
3. Standard crop from top-center position

Invalid quality values automatically default to balanced with a warning in debug output.

Usage Notes

Debug information

Using debug="yes" shows face detection processing details:

• Quality mode used
• Detection time in milliseconds
• Number of faces detected
• Face coordinates (x, y, width, height)
• Whether cache was used or detection ran
• Fallback behavior if no faces found

Example: crop="face_detect" face_detection_quality="accurate" debug="yes"

Usage Notes

Migration from JCOGS Image

Legacy JCOGS Image format (still works):

crop="face_detect" face_detect_sensitivity="5"

Pro recommended format:

crop="face_detect" face_detection_quality="balanced"

Pro advanced format (both parameters):

crop="face_detect" face_detection_quality="accurate" face_detect_sensitivity="7"

The named quality modes (fast, balanced, accurate) are more semantic and self-documenting than numeric sensitivity values, making templates easier to understand and maintain.

Usage Notes

Filter chain order matters

Filters are applied sequentially from left to right. The order significantly impacts the final result:

• blur:5|sharpen:10 - Blurs first, then attempts to sharpen (less effective)
• sharpen:10|blur:5 - Sharpens first, then blurs (different result)
• grayscale|contrast:1.5 - Converts to grayscale, then boosts contrast (recommended)
• contrast:1.5|grayscale - Boosts color contrast, then converts to grayscale (contrast boost wasted)

For optimal results, apply color manipulations (colorize, sepia, grayscale) before tonal adjustments (brightness, contrast), and apply sharpening as the final step.

Usage Notes

Performance considerations

Filter processing adds computational overhead:

• Simple filters (brightness, contrast) - Minimal impact, typically 1-3ms
• Medium filters (sharpen, blur, grayscale) - Moderate impact, typically 3-8ms
• Complex filters (emboss, edge_enhance, colorize) - Higher impact, typically 8-15ms

Processing time scales with image dimensions. Always use the cache parameter when applying filters to avoid repeated processing. Multiple filters in a chain increase processing time additively.

Usage Notes

Optimal parameter ranges

While filters accept wide parameter ranges, certain values produce most useful results:

• blur - Values 2-10 work best. Above 20 creates extreme blur.
• sharpen - Values 5-20 effective. Above 40 creates artifacts.
• brightness - Adjustments of ±20 most common. Beyond ±50 risks clipping.
• contrast - Range 0.8-1.5 most useful. Below 0.5 or above 2.0 creates unusual effects.
• pixelate - Values 5-20 create recognizable effect. Above 30 severely degrades image.

Start with conservative values and adjust incrementally for best results.

Usage Notes

Combining filters strategically

Certain filter combinations produce professional results:

• Product photography: brightness:10|contrast:1.2|sharpen:12
• Vintage effect: sepia|contrast:0.9|brightness:-5
• Dramatic B&W: grayscale|contrast:1.6|brightness:-10
• Soft portrait: blur:2|brightness:5|sharpen:8
• High contrast color: contrast:1.4|brightness:5|sharpen:15

Experiment with combinations but limit chains to 3-4 filters to maintain processing performance and avoid compounding artifacts.

Usage Notes

Filter quality and artifacts

Aggressive filter settings can introduce visual artifacts:

• Sharpening artifacts - Halos around edges, exaggerated noise. Reduce sharpen amount or apply noise reduction first.
• Brightness clipping - Lost detail in highlights/shadows. Use moderate adjustments (±30 maximum).
• Blur banding - Visible steps in gradients. Use moderate blur values (under 15).
• Pixelation loss - Unreadable text/details. Keep block_size under 20 for legibility.

Always preview filtered images at target display size to evaluate quality before deployment.

Usage Notes

Format-specific considerations

Filter effects interact differently with image formats:

• JPEG - Compression artifacts can be amplified by sharpening. Use moderate sharpen values (under 15).
• PNG - Lossless format preserves filter details perfectly. Ideal for complex filter chains.
• WebP - Excellent filter preservation with smaller file sizes than PNG.
• GIF - Limited color palette makes colorize and sepia filters less effective.

For heavily filtered images, consider PNG or WebP output to preserve quality. Adjust quality parameter for JPEG to balance file size and filter detail preservation.

Usage Notes

Browser-side vs server-side filtering

JCOGS Image Pro applies filters server-side during image processing, which offers advantages over CSS filters:

• Performance - Processed once and cached, no runtime CPU/GPU usage
• Compatibility - Works in all browsers, including old versions
• SEO - Search engines see the filtered image
• Consistency - Identical appearance across all devices and browsers

Use server-side filtering for permanent effects. Reserve CSS filters for interactive hover effects or user-controlled adjustments.

Usage Notes

Accessibility with filters

Certain filter effects impact accessibility:

• Grayscale/Sepia - May reduce color-based information. Ensure content doesn't rely solely on color cues.
• Low contrast - Values below 0.8 may fail WCAG contrast requirements. Test with accessibility tools.
• Brightness extremes - Very bright (>50) or dark (<-50) images strain vision. Use moderate values.
• Blur - Can make text unreadable. Avoid blur on images containing critical text.

Always provide meaningful alt text describing filtered images, especially when filters significantly change appearance.

Usage Notes

Testing filter combinations

Develop an efficient workflow for finding optimal filter settings:

1. Start with single filters to understand their individual effects
2. Add filters one at a time to build chains incrementally
3. Test on multiple source images - effects vary by content
4. View at actual display size - filters appear different at various scales
5. Use short cache durations during testing (e.g., cache="1 minute")
6. Document successful combinations for reuse in presets

Once finalized, switch to longer cache durations (hours or days) for production use to maximize performance.

Usage Notes

If the parameter is specified with no value (e.g. fit="") or an unrecognised value it is ignored and the default value is used.

Usage Notes

Transparency

Not all formats support transparency. Where possible transparency in images is preserved by JCOGS Image Pro during processing, but it is also important to make sure that the processed image is saved in a format that also supports transparency: in particular if you are manipulating a PNG image with transparency and wish the processed image to retain this transparency, make sure you specify save_type="png" in your tag.

Not all filter operations preserve transparency.

When transparency is removed during a operation, the transparent pixes are replaced by pixels coloured according to whatever colour is chosen as the default background colour.

Usage Notes

Lossy vs Lossless

JCOGS Image Pro always attempts to save images using the smallest file size option available for any given format. So for PNG and WebP images which support both lossy and lossless image storage formats, the images are saved using the lossy (compressed) format. 

When JCOGS Image is run on a server providing php 8.1, when a webp format image is saved with a quality value of 100 it will be saved in webp's lossless image format.

Usage Notes

Static Caching vs. Image Format Detection

JCOGS Image Pro will actively attempt to ensure that your images are presented to a browser in a format that the browser can read. However for this active engagement to work, JCOGS Image Pro has to be able to communicate with the browser. Due to how static caching works, JCOGS Image Pro will not be able to make any adjustments to the images sent to a browser on pages that are in a static cache, and so you should be cautious about what image format you choose for pages that will be delivered in this way.

One option is to specify ‘safe’ formats (such as JPG, PNG, GIF) for your images - these formats have effectively universal support.

Another option is to code up your pages using the HTML <picture> tag - which lets you specify multiple formats for the same image, and the browser can then choose a version it can read from those offered.

 A future update to JCOGS Image Pro will add in the ability to auto-generate <picture> tags for this purpose, but for now you will need to code up your own versions, making use of JCOGS Image Pro variables to construct the tags to your liking.

Usage Notes

SVG Format

JCOGS Image Pro currently provides limited support for SVG files. That support does not currently include the ability to convert images from or to the SVG format, and so if you specify svg as the format this value will be ignored and the default image format will be used instead.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_height= or max_height= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

This parameter is ignored if the save_type= or format= parameter is set to anything other than jpg.

Usage Notes

Use with manually constructed <img> tags

To use lazy loading if you are generating output using using JCOGS Image Pro Variables, e.g. via a tag-pair configuration or use of the output= parameter in a single tag then you will also need to manually include the background style element required, and a prompt within the same tag to trigger the creation of a “preload” instruction for the lazy loading image chosen.

Fortunately there is a JCOGS Image Pro Variable that can help with this: lazy_image contains the URL to the chosen lazy loading image (e.g. lqip or dominant colour), so the additional elements you need to include in your manually constructed tag are: 

• style=“background-image: url('{lazy_image}');”
• data−bglzy="{lazy_image}"

The second of these two elements will be removed by JCOGS Image during template parsing and will cause it also to add a preload instruction to the HTML <header> section.

Usage Notes

Using lazy loading with images that have transparency

You might wish to be cautious about using JCOGS Image Pro's default “background image” approach to Lazy Loading with images that have transparency: since for this approach, the lazy image (lqip or dominant colour) is loaded in the image background and then overlaid by the full resolution image; during this process the background is not removed. It is likely that both the dominant colour and lqip versions of the image with transparency will occupy more pixels than the full resolution image and so when the full resolution image is overlaid parts of the background ‘lazy’ image will continue to be visible. 

Where this is likely to happen, the best option is to either disable lazy loading for the affected images, or choose the alternative javascript based lazy loading approach (which does replace the lazy image with the full resolution image.

Usage Notes

Choosing the right mode

• lqip - Best visual experience, shows preview immediately. Recommended for most sites.
• dominant_color - Lightest placeholder, good for simple layouts or bandwidth-sensitive scenarios.
• js_lqip / js_dominant_color - Use when strict Content Security Policy prevents inline styles.
• html5 - Simplest implementation, modern browsers only. No placeholder but smallest overhead.

Usage Notes

Browser compatibility

LQIP and dominant color modes work in all browsers via JavaScript fallback. HTML5 mode requires browser support for native lazy loading (Chrome 76+, Firefox 75+, Safari 15.4+, Edge 79+). Older browsers load images immediately when using html5 mode.

Usage Notes

Performance impact

Lazy loading significantly improves initial page load:

• Reduces initial bandwidth by 40-60% on image-heavy pages
• Improves Largest Contentful Paint (LCP) metric for above-fold content
• Decreases time to interactive by deferring below-fold image processing

LQIP mode adds small overhead (5-10KB per image) for placeholder generation but provides best user experience.

Usage Notes

Global settings vs parameter

Lazy loading can be enabled globally in JCOGS Image Pro settings or per-image via lazy parameter. Parameter value overrides global setting. Use lazy="no" to disable for specific images (like hero images or above-the-fold content).

Usage Notes

Combining with srcset

Lazy loading works seamlessly with responsive srcset images. Correct image variant loads based on viewport when image becomes visible:

lazy="lqip" srcset="400w|800w|1200w"

Placeholder displays immediately, then appropriate srcset variant loads when scrolled into view.

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for max_width= or max_height= in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or max= parameters in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

Precedence

This parameter will over-rule any explicit setting for width= or height= in a tag.

This parameter will be over-ruled by any setting for min_width= or min_height= in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the height= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

Precedence

This parameter will over-rule any explicit setting for the width= or min= parameters in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image. 

Usage Notes

When this parameter is specified, the value of the create_tag= parameter is ignored. 

Usage Notes

Precedence

If set to yes this parameter over-rules any other cache settings in the tag or set in the JCOGS Image Pro Control Panel Settings area. If set to no, other cache settings will be tested before a decision is made about whether to use a cached copy of an image.

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than png.

Usage Notes

Preload is only applied to <img> tags that are generated by JCOGS Image. If you ask JCOGS Image Pro to output things other than complete <img> tags (e.g. url_only="yes" or output=) then the preload= tag will be ignored.

Usage Notes

Common preset use cases

Presets excel at maintaining consistency across your site:

• Responsive image sets: Define presets for different viewport sizes (mobile, tablet, desktop)
• Content type styling: Create presets for different content types (thumbnails, hero images, avatars, cards)
• Brand consistency: Maintain consistent image treatments, borders, effects across your site
• Performance optimization: Pre-configure optimal quality and dimension settings
• Team collaboration: Share parameter configurations across development teams without documentation

Usage Notes

Example preset definitions

While preset definitions are configured at the system level, here are example configurations demonstrating common patterns:

Thumbnail Preset:

• width: 150
• height: 150
• crop: yes
• quality: 80
• save_as: jpg

Hero Image Preset:

• width: 1920
• height: 800
• crop: yes
• quality: 85
• save_as: jpg
• lazy: native
• fetchpriority: high

Avatar Preset:

• width: 64
• height: 64
• crop: yes
• aspect_ratio: 1:1
• quality: 80
• rounded_corners: 50%
• save_as: png

Gallery Thumbnail Preset:

• width: 300
• height: 200
• crop: yes
• quality: 82
• save_as: jpg
• lazy: yes
• srcset: 300,600,900

Usage Notes

Overriding preset parameters

Tag-level parameters always take precedence over preset parameters. This allows you to use presets for consistency while maintaining flexibility:

preset="thumbnail" (uses all preset defaults)

preset="thumbnail" width="200" (overrides width only)

preset="thumbnail" width="200" quality="90" (overrides width and quality)

Any parameter can be overridden. There's no limit to the number of overrides - if needed, you can override every parameter in the preset, though at that point using a different preset or no preset might be more appropriate.

Usage Notes

Debug information

When using debug="yes", the system logs preset processing information:

• Preset name used
• Number of parameters loaded from preset
• Number of tag-level parameters
• Final merged parameter count
• Any preset resolution errors or warnings
• Parameter override details

Example: preset="thumbnail" debug="yes"

This is invaluable for troubleshooting preset configurations and understanding which parameters are coming from the preset vs tag overrides.

Usage Notes

Error handling and fallback

The preset system degrades gracefully when issues occur:

• If the specified preset name doesn't exist, the tag processes normally using only tag-level parameters and defaults
• Invalid preset definitions are logged but don't cause tag failure - invalid parameters are skipped
• Missing PresetResolver service degrades gracefully with a logged warning - tags still process
• Empty preset parameter values can be used to explicitly unset preset defaults

This ensures that preset-related issues don't break image rendering. Check debug output or logs to diagnose preset problems.

Usage Notes

Performance considerations

Preset usage has minimal performance impact:

• Resolution overhead: Presets are resolved once per tag execution (~0.1ms typical)
• Parameter merging: Merging preset and tag parameters adds negligible overhead
• Caching: Preset definitions are cached by the PresetResolver service for efficiency
• Cache keys: Final resolved parameters (not preset names) are used in cache key generation

Using presets does not affect cache efficiency - two tags with the same preset and identical overrides will share the same cached image.

Usage Notes

Preset naming conventions

Follow these conventions for clear, maintainable preset names:

• Descriptive names: Use names that describe purpose (thumbnail, hero, avatar) not appearance (small, big, round)
• Lowercase with underscores: gallery_thumb, product_detail, hero_image
• Avoid generic names: "default", "standard", "normal" are ambiguous - be specific
• Context prefixes: blog_thumbnail, product_hero, member_avatar for clarity
• Case sensitivity: Preset names are case-sensitive - maintain consistency

Usage Notes

Preset limitations

Be aware of these preset system constraints:

• No nesting: Presets cannot reference other presets - each preset is standalone
• No inheritance: No parent-child preset relationships - consider using parameter package defaults instead
• Single preset per tag: Only one preset can be specified per image tag
• Static definitions: Presets are defined at the configuration level, not dynamically per request

For complex inheritance requirements, consider using multiple image tag templates or wrapper templates with varying parameter sets.

Usage Notes

When NOT to use presets

Presets are not always the best solution:

• One-off images: Unique images with unusual requirements may be clearer with explicit tag parameters
• Highly variable parameters: If you find yourself overriding most preset parameters, reconsider preset usage
• Simple sites: Small sites with few image variations may not benefit from preset overhead
• Documentation priority: If tag readability is critical, explicit parameters may be clearer than preset references

Presets excel when you have consistent, repeated image treatments across many pages or components.

Usage Notes

Migration and maintenance

Preset-based templates are easier to maintain and update:

Without presets (parameters repeated everywhere):

Changing thumbnail size requires finding and updating dozens or hundreds of image tags across your templates.

With presets (centralized configuration):

Update the "thumbnail" preset definition once, and all thumbnail images site-wide automatically reflect the new dimensions on next cache regeneration.

This centralized control makes site-wide changes manageable and reduces the risk of inconsistencies from incomplete updates.

Usage Notes

This parameter is ignored if the save_type= parameter is set to anything other than webp or jpg.

Usage Notes

Saving Images using Webp Lossless Format

For servers running php 8.1 or better setting the quality value to 100, or setting the quality value to lossless will cause webp format images to be saved in webp's lossless format.

Usage Notes

Dimension increases with reflection

Adding a reflection increases the final image dimensions vertically. The total height becomes:

Final Height = Original Height + Gap Height + Reflection Height

For example:

• Original: 400×300px
• Reflection: gap=10px, height=50% (150px)
• Final: 400×460px (300 + 10 + 150)

This is important when sizing images for specific layouts or containers. You may need to adjust your height parameter to account for the additional reflection space.

Usage Notes

Opacity gradient behavior

The opacity gradient is applied linearly from the top of the reflection (start opacity) to the bottom (end opacity):

• Standard fade: 80|0 - Fades from 80% opacity to fully transparent (most common)
• Gentle fade: 60|20 - Never fully transparent, maintains subtle reflection at bottom
• No fade: 50|50 - Uniform 50% opacity throughout reflection
• Inverse fade: 0|80 - Starts transparent, becomes more opaque (unusual but possible)

The gradient always progresses linearly between the two values regardless of which is higher.

Usage Notes

Gap spacing

The gap attribute (1st position) creates vertical space between the bottom of the main image and the top of the reflection. This is useful for:

• No gap (0): Creates immediate reflection effect, like a mirror surface
• Small gap (5-10px): Subtle separation, common for product photography
• Larger gap (20px+): More pronounced separation, artistic effect
• Percentage gap (5%): Scales with image size, maintains proportions across different sizes

The gap space is transparent (or uses bg_color if specified for non-transparent formats).

Usage Notes

Using reflection with JPEG format

JPEG format does not support alpha channel transparency, so reflections on JPEG require a background color to be specified. Without bg_color, the transparent reflection areas will appear as solid color (typically white or black depending on image library).

Recommended approach for JPEG:

reflection="10px|70|0|50%" bg_color="white" format="jpg"

With JCOGS Image Pro's CSS color support, you can use named colors for easy specification:

reflection="10px|70|0|50%" bg_color="aliceblue" format="jpg"

Usage Notes

Reflection height considerations

The height attribute (4th position) controls how tall the reflection appears:

• 50%: Default, half the image height - most common and visually balanced
• 30-40%: Shorter reflection, more subtle effect
• 60-80%: Taller reflection, more dramatic effect
• 100%: Full-height reflection, mirrors entire image

Percentages are calculated relative to the original image height. For example, a 300px tall image with height:50% produces a 150px tall reflection.

You can also specify absolute pixel values: height:200px creates a 200-pixel tall reflection regardless of image size.

Usage Notes

Performance considerations

Reflection processing is relatively lightweight:

• Processing time: Adds approximately 3-8ms depending on reflection height and image size
• File size impact: Increases file size due to additional image area (proportional to reflection height)
• Caching: Always cache reflection images (use cache parameter) to avoid repeated processing

Reflections with shorter heights and simpler opacity gradients process slightly faster than full-height reflections.

Usage Notes

Combining reflection with other transformations

Reflections work well with most other JCOGS Image Pro transformations:

• Compatible: border, rounded_corners, filter, watermark, text
• Special consideration: When combining with rounded_corners, ensure output format supports transparency (PNG/WebP)
• Application order: Reflection is applied after most other transformations, so border/corners affect both the original and reflection

Example: rounded_corners="20px" border="5|gray" reflection="10px|70|0|50%" format="png"

Usage Notes

Typical use cases

Reflections are commonly used for:

• Product photography: Creates professional "on glass" effect
• Logo presentations: Adds visual depth and polish
• Promotional graphics: Enhances perceived quality and sophistication
• App screenshots: Modern presentation style popular in software marketing

Best results are achieved with images that have clean, defined edges and simple backgrounds. Busy or complex background images may create distracting reflections.

Usage Notes

Minimal syntax shortcut

To apply a reflection with all default settings, simply use reflection="0" or even just reflection (though the first form is clearer).

This applies:

• No gap (0)
• 80% start opacity
• 0% end opacity (fully transparent)
• 50% height

Most use cases work well with default settings, requiring only format specification: reflection="0" format="png"

Usage Notes

Precedence

The rotation operation is applied after crop and resize operations, and after image flip operations.

Usage Notes

Transparency requirements

Rounded corners require image formats that support transparency (alpha channel):

• PNG - Recommended, excellent transparency support
• WebP - Modern format with transparency
• GIF - Supports transparency but limited colors

For JPEG output (no transparency), specify corner color parameter to fill rounded areas with solid color instead of transparency.

Usage Notes

Percentage vs pixel radius

Choose radius units based on your needs:

• Pixels (20px) - Absolute sizing, consistent appearance across all image dimensions
• Percentages (15%) - Relative sizing, scales proportionally with image size
• Unitless (20) - Interpreted as pixels

Percentages calculated relative to shortest image dimension to prevent excessive rounding on narrow images.

Usage Notes

Override pattern

When using all with individual corners, individual specifications override the general setting:

rounded_corners="all,20|tl,40|br,40"

This sets all corners to 20px, then overrides top-left and bottom-right to 40px. Final result: TL=40px, TR=20px, BL=20px, BR=40px.

Usage Notes

Performance considerations

Rounded corner processing is relatively lightweight (typically 2-5ms) but requires transparency-capable formats which have larger file sizes than JPEG. Balance appearance needs with file size:

• WebP with rounded corners - Best balance of quality and file size
• PNG with rounded corners - Larger files but maximum quality
• JPEG with corner colors - Smallest files but no true transparency

Always use cache parameter to avoid repeated processing.

Usage Notes

Combining with other effects

Rounded corners work well with complementary effects:

• With border: rounded_corners="all,20" border="5|#333" - Border follows rounded shape
• With shadow: Add CSS box-shadow for depth perception
• With reflection: rounded_corners="all,15" reflection="10px" - Reflection includes rounded shape

Avoid combining with heavy filters that may create artifacts at rounded edges.

Usage Notes

CE Image Compatibility Note: The CE Image facility to specify a different background colour for each corner is not supported. To specify a background colour to use where corners are being applied to a non-transparent image format, use the bg_color parameter to specify the same colour to use for all the corners defined.

Usage Notes

Transparency

Not all formats support transparency. Where possible transparency in images is preserved by JCOGS Image Pro during processing, but it is also important to make sure that the processed image is saved in a format that also supports transparency: in particular if you are manipulating a PNG image with transparency and wish the processed image to retain this transparency, make sure you specify save_type="png" in your tag.

Not all filter operations preserve transparency.

When transparency is removed during a operation, the transparent pixes are replaced by pixels coloured according to whatever colour is chosen as the default background colour.

Usage Notes

Lossy vs Lossless

JCOGS Image Pro always attempts to save images using the smallest file size option available for any given format. So for PNG and WebP images which support both lossy and lossless image storage formats, the images are saved using the lossy (compressed) format. 

When JCOGS Image Pro is run on a server providing php 8.1, when a webp format image is saved with a quality value of 100 it will be saved in webp's lossless image format.

Usage Notes

Static Caching vs. Image Format Detection

JCOGS Image Pro will actively attempt to ensure that your images are presented to a browser in a format that the browser can read. However for this active engagement to work, JCOGS Image Pro has to be able to communicate with the browser. Due to how static caching works, JCOGS Image Pro will not be able to make any adjustments to the images sent to a browser on pages that are in a static cache, and so you should be cautious about what image format you choose for pages that will be delivered in this way.

One option is to specify ‘safe’ formats (such as JPG, PNG, GIF) for your images - these formats have effectively universal support.

Another option is to code up your pages using the HTML <picture> tag - which lets you specify multiple formats for the same image, and the browser can then choose a version it can read from those offered.

 A future update to JCOGS Image Pro will add in the ability to auto-generate <picture> tags for this purpose, but for now you will need to code up your own versions, making use of JCOGS Image Pro variables to construct the tags to your liking.

Usage Notes

SVG Format

JCOGS Image Pro currently provides limited support for SVG files. That support does not currently include the ability to convert images from or to the SVG format, and so if you specify svg as the save_type this value will be ignored and the default image format will be used instead.

Usage Notes

This tag is ignored if a srcset= parameter is not also defined within the JCOGS Image tag.

Usage Notes

How browsers use sizes

Browser combines sizes with srcset to select optimal image:

1. Evaluates sizes media conditions to determine image display width
2. Considers device pixel ratio (e.g., 2x for retina)
3. Calculates required image width (display width × pixel ratio)
4. Selects closest srcset variant that meets or exceeds required width

Accurate sizes specification helps browsers make optimal choices and avoid downloading unnecessarily large images.

Usage Notes

Default sizes behavior

If sizes is omitted but srcset is present, browsers assume sizes="100vw" (image fills viewport). This often causes desktop users to download mobile-optimized images when they need larger variants. Always specify sizes when using srcset for best results.

Usage Notes

Match your layout breakpoints

Sizes media conditions should match your CSS layout breakpoints:

• If CSS makes images full-width on mobile (≤768px), use (max-width: 768px) 100vw
• If CSS creates 2-column grid on tablet (769-1024px), use (max-width: 1024px) 50vw
• If CSS fixes content width at 1200px on desktop, use default 1200px

Mismatched breakpoints result in suboptimal image selection and wasted bandwidth.

Usage Notes

Using calc() for margins

When images have fixed margins/padding that don't scale with viewport:

sizes="(max-width: 768px) calc(100vw - 40px), 1200px"

This tells browser image is full viewport minus 40px of padding on mobile. More accurate sizing = better variant selection.

Usage Notes

Debugging sizes selection

Browser DevTools Network tab shows which srcset variant was selected. If browser chooses unexpected variant:

• Check sizes media conditions match actual breakpoints
• Verify width values accurately reflect image display size
• Remember retina displays may select 2x larger images
• Test at actual device widths, not just browser resize

Well-configured sizes dramatically improves bandwidth efficiency on mobile devices.

Usage Notes

What happens if the src parameter is empty / blank?

If the src parameter is missing , or is supplied with an empty value in an image, single or pair tag, JCOGS Image will first attempt to substitute either the nominated fallback_src image (if there is one specified in the tag) or consult the defaults in Image Settings to see if a global default for fallback image has been provided: if it is able to use a fallback alternative it will.

If no fallback alternative is available, JCOGS Image Pro will end processing of the tag without doing any processing.

Usage Notes

Remote Image Files

If a remote source image file is specified the source file will be downloaded to the local server before processing begins, which adds time to the total processing time for the template holding the JCOGS Image Pro tag.

If a remote image is not obtained within a reasonable period, or if it is found to be unavailable, JCOGS Image Pro will first attempt to use a fallback_src= image. If no fallback image is specified, or if that image too is unavailable, JCOGS Image Pro will terminate processing of the tag.

The default caching setup for JCOGS Image Pro enables the add-on to avoid the need to download or process the remote source image again in subsequent calls to the template: for site performance reasons you are strongly encouraged to retain these settings for remote image files (either by leaving the add-on with default settings, or adding cache= parameter to your tags with remote image sources).

Usage Notes

Tip 

Mozilla's Dev site has a good introductory explanation of responsive image principles

Usage Notes

Choosing breakpoint widths

Select srcset widths based on common device categories:

• Mobile: 320px, 375px, 414px
• Tablet: 768px, 1024px
• Desktop: 1280px, 1440px, 1920px

Typically 3-5 variants provide good balance. More variants = more cache storage but finer optimization.

Usage Notes

Srcset with sizes parameter

Srcset works best with sizes parameter which tells browser how much viewport width image will occupy:

srcset="400|800|1200" sizes="(max-width: 768px) 100vw, 50vw"

Without sizes, browser assumes image fills viewport width (100vw).

Usage Notes

Pixel-Density Mode Behaviour

In density mode, each descriptor is converted into a target width by multiplying the processed base width by the density value.

• Example: base width 236 with srcset="1x|2x" requests 236px and 472px candidates.
• If a target exceeds allowed limits, that candidate is skipped unless allow_scale_larger="yes" allows larger generation.
• The 1x candidate can map to the main processed image (no duplicate file generation needed).

Usage Notes

sizes with Width vs Density Modes

• Width mode: sizes is strongly recommended and drives width-based candidate selection.
• Density mode: if custom sizes is provided it is passed through to the output, but it does not control x-descriptor candidate selection.
• Density mode without sizes: no auto-generated sizes attribute is emitted.

Usage Notes

Note about using with the allow_scale_larger parameter

The role of srcset is to help the browser download the optimum size (i.e. smallest) image for the browser conditions encountered: for example if you are viewing an image on a mobile device, the user will get better performance if an appropriate sized image is downloaded rather than one designed for full-size browser windows.

Because of this, under normal conditions it does not make sense to have srcset generate alternative images that are larger than the processed image: the user will get an equivalent experience from the processed image being downloaded and scaled up in the browser. Accordingly srcset's default behaviour is to only generate variants of the processed image that are smaller.

However, under some conditions it might be useful for this rule to be broken - for example if your processed image includes filter effects such as text or image overlays, where the overlay element might be rendered more sharply on a scaled up image than would be case for base processed image being enlarged in the browser.

To allow for this, if you set allow_scale_larger="yes" as a parameter in your tag, Image will set the processed image width to match the largest valid srcset width encountered, and process the image accordingly, even if this width is larger than the nominal width of the processed image.

Usage Notes

Cache implications

Each srcset variant is cached separately. A srcset with 4 widths creates 4 cached files. Consider storage when choosing number of variants. Use cache parameter to control cache duration.

Usage Notes

Performance benefits

Srcset dramatically improves performance on mobile:

• 40-70% bandwidth reduction on mobile devices
• Faster page loads on slower connections
• Improved Core Web Vitals scores

Always use srcset for hero images and large content images in responsive designs.

Usage Notes

Automatic word wrapping

Text is automatically word-wrapped to fit within the image width (or the specified box width if narrower). Line breaks can be forced using \n in your text content. The line_height attribute controls vertical spacing between wrapped lines.

If text is too long to fit within the available space even after wrapping, the text will be truncated at the bottom of the text box. Consider reducing font_size or increasing the image dimensions if truncation occurs.

Usage Notes

Custom fonts

To use a custom font, specify the path to a TrueType (.ttf) font file in the font_src attribute (6th position or font:path in named format). The path should be relative to your ExpressionEngine web root.

Example: text="My Text||24px|||/assets/fonts/custom-font.ttf" or text="content:My Text|font:/assets/fonts/custom-font.ttf|font_size:24px"

If the specified font file cannot be found or loaded, JCOGS Image Pro will fall back to the default Voces Regular font. Check debug output if fonts aren't displaying as expected.

Usage Notes

Text positioning and offset

The position attribute (9th position) provides coarse positioning (left/center/right, top/center/bottom), while the offset attribute (10th position) provides fine-tuned pixel-level adjustment from that position.

For example, position:right,bottom|offset:-20,-20 positions text in the bottom-right corner with a 20-pixel margin from both edges.

Usage Notes

Shadow effects for readability

Adding a drop shadow using shadow_color (12th attribute) and shadow_offset (13th attribute) significantly improves text readability over complex or varying backgrounds. A common pattern is semi-transparent black shadow:

text="content:Title|color:white|shadow_color:rgba(0,0,0,0.7)|shadow_offset:2,2"

The shadow is rendered first, then the main text is drawn on top. Shadow opacity can be controlled independently via shadow_opacity (14th attribute).

Usage Notes

Text box vs text character backgrounds

JCOGS Image Pro provides two types of backgrounds for text:

• Text Box Background (15th attribute, box_bg) - Draws a rectangular background behind the entire text box, extending to the box edges. Useful for creating banner-like effects.
• Text Background (16th attribute, text_bg) - Draws backgrounds directly behind individual text characters, following character shapes. Creates a tighter background effect.

Both support semi-transparent colors using rgba() format. They can be used together, though this is uncommon.

Usage Notes

Box width adjustment

The box_width attribute (8th position) constrains the text box width:

• Positive values: Absolute width in pixels (e.g., 400 = 400px wide text box)
• Negative values: Reduction from full image width (e.g., -40% = text box is 40% narrower than image width, or -100 = 100px narrower)
• Percentages: Interpreted based on sign. Positive percentage = that percentage of image width, negative percentage = reduce by that percentage

Constraining box width is useful for multi-line text that you want to wrap at a specific width rather than the full image width.

Usage Notes

Rotation (Pro feature - 17th attribute)

JCOGS Image Pro adds a 17th attribute not present in CE Image: rotation. This allows text to be rotated at any angle:

• Positive values: Clockwise rotation (e.g., 45 = 45° clockwise)
• Negative values: Counter-clockwise rotation (e.g., -30 = 30° counter-clockwise)
• Range: Typically 0-360 degrees, but values outside this range are normalized

Rotated text is useful for diagonal watermarks, artistic effects, or fitting text into angled design elements.

Legacy format: text="SAMPLE||72|||||||||||||45" (note 13 empty positions)
Named format: text="content:SAMPLE|font_size:72|rotation:45" (much clearer!)

Usage Notes

Performance considerations

Text rendering is more resource-intensive than most other image operations:

• Simple text: Adds 5-15ms to processing time
• Multi-line text: Adds 10-25ms depending on text length and wrapping
• Custom fonts: First use loads font file (20-50ms), subsequent uses cached (5-15ms)
• Shadows and backgrounds: Add 3-8ms each
• Rotation: Adds 5-10ms for transformation calculations

Always ensure text-overlaid images are cached (cache parameter) for production use to avoid repeated processing overhead.

Usage Notes

This is one of the several ways in which JCOGS Image Pro can be instructed to provide just a URL to the processed image.

Usage Notes

Watermark image format recommendations

The best watermark images have transparent backgrounds, allowing them to overlay cleanly on any image content. Supported formats with transparency include:

• PNG - Best choice, widely supported, excellent transparency
• WebP - Modern format with good compression and transparency support
• GIF - Older format, limited colors but supports transparency

JPEG format does not support transparency and will appear with a rectangular background. If using JPEG watermarks, the opacity parameter will still apply to the entire image including its opaque background.

Usage Notes

Opacity control

The opacity attribute (3rd position or opacity:value in named format) controls the overall transparency of the watermark overlay:

• 0 - Completely transparent (invisible, watermark not applied)
• 50 - Semi-transparent (common for subtle branding)
• 100 - Fully opaque (default, watermark appears at full strength)

This opacity is applied uniformly to the entire watermark image, including any existing transparency in the source watermark. For example, a PNG watermark with 50% transparent areas set to 50% opacity will have those areas at 25% overall opacity (50% × 50%).

Usage Notes

Rotation and its effects

The rotation attribute (6th position or rotation:degrees) rotates the watermark anti-clockwise around its center point:

• Positive values: Anti-clockwise rotation (e.g., 45 = 45° anti-clockwise)
• Negative values: Clockwise rotation (e.g., -30 = 30° clockwise)
• Range: Any integer degree value (values outside 0-360 are normalized)

Important: In repeat mode, rotation is applied to each watermark instance individually. Combined with diagonal spacing, this creates sophisticated tiled patterns suitable for document watermarking.

Usage Notes

Repeat mode for copyright protection

Using repeat mode creates a tiled watermark pattern across the entire image, making unauthorized removal more difficult:

Recommended settings for copyright protection:

• Opacity: 15-30% (subtle but visible)
• Spacing: 80-150px both directions
• Rotation: 30-45 degrees (diagonal pattern)
• Watermark size: Small enough to not obscure content (typically 10-20% of image width)

Example: watermark="src:copyright.png|opacity:20|position:repeat,100px,100px|rotation:45"

Usage Notes

Performance considerations

Watermark application adds processing time depending on complexity:

• Single watermark: Adds 2-8ms depending on watermark size
• Repeated watermarks: Adds 10-40ms depending on number of instances
• Rotated watermarks: Add 2-5ms per instance for rotation calculations
• Remote watermarks: Add network fetch time (first use only, then cached)

Always ensure watermarked images are cached (via the cache parameter) for production use to avoid repeated processing overhead.

Usage Notes

Watermark source paths

Watermark source can be specified as:

• Relative path: /media/a_word_from_our_sponsor.png (relative to site web root)
• Absolute path: Full filesystem path (less common)
• Remote URL: https://cdn.example.com/watermark.png (fetched and cached)
• EE File field: {cf_logo} (channel field containing image path)

Remote URLs are fetched once and cached locally for subsequent uses.

Usage Notes

Backward compatibility

Both JCOGS Image and CE Image's position-dependent format and the newer named attributes format produce identical results. Existing templates using the legacy format will continue to work without modification. The named attributes format is recommended for new implementations due to improved readability and maintenance.

Watermark parameter is fully compatible with CE Image's watermark implementation with the addition of Pro's named attribute system.

Usage Notes

Precedence

This parameter will be potentially over-ruled by any explicit settings for  min_width= or max_width= or min= or max= in a tag.

% values

If a % value is specified, JCOGS Image Pro works out the equivalent value in pixels based on the width or height of the original image, except when they are used in max= or min= parameters, where the % values are always based on the width of the original image.