Advanced TopicsLast updated: 12 November 2025
Some aspects of JCOGS Image Pro operation are more complex than can be covered in the definition of a parameter or variable or filter.
In this section some of these more complex aspects are discussed in more detail.
Animated GIF Support
Passthrough Support for Animated GIF Images
The aim of this feature is to allow animated GIF images to be functionally included within image workflows.
When JCOGS Image Pro detects that a source image is an animated GIF, and when the output format selected for the image is also GIF (either by default, or because of a save_type= parameter setting) Image will ignore all Image parameters in the relevant tag except Image Sizing instructions, and will generate a processed image that is also an animated GIF that will be included in JCOGS Image Pro's unified caching system.
The aim of this level of support is to remove the first obstacle to integrating Animated GIF images more fully into your web design workflow. It is recognised that this is a small (but useful and important) step.
Extending Animated GIF Support - adding the ability to force the behaviour even when save_type is specified
Since Passthrough support was introduced some users have noted that under some circumstances animated GIF images are still being collapsed to still images. This was found to be occurring when a site-wide default image format had been set (e.g. to webp) - this setting was overriding the Animated GIF passthrough support. To address this, the catchily titled “Enable dominance for preserving animated gif image formats” seting tells JCOGS Image Pro to ignore save_type= and format= parameter values when it is working with Animated GIF images.
Lazy Loading
Lazy loading is a technique to speed up the loading of image intensive pages: in its simplest form lazy loading prevents the downloading images that are outside the part of the screen currently being viewed by the user.
The simple implementation can lead to multiple issues that present to the user through a degraded experience both visually (for example layout ‘jank’) and functionally (causing problems for users of assistive technologies).
JCOGS Image Pro's default approach to lazy loading uses an approach that is both effective and avoids user experience issues: the method exploits browser's support for background images to be applied to elements in a page, and has been shown to produce very low “Largest Contentful Paint” (LCP) times.
For cases where the background-first approach to loading lazy images is not appropriate, JCOGS Image provides an alternative javascript based implementation approach that supports progressive enhancement, is efficient, fast and offers strong compatibility with current browsers.
Use of JCOGS Image Pro Lazy loading is triggered by adding the lazy= parameter to a tag, or by enabling it as a system default in the JCOGS Image add-on control panel area.
Starting with a plain tag <img src="my_image.jpg">, JCOGS Image Pro's default approach to lazy loading does the following:
- it adds an inline style parameter to the tag setting the lazy loading placeholder image as the image background: to ensure that the image is sized correctly from the outset it also adds the image dimensions to the tag;
<img src="my_image.jpg"loading="lazy" style="background-image: url(lqip_my_image.jpg)"> - it adds an additional instruction to the <head> area of the page HTML instructing the browser to download the placeholder image as a priority on page load;
<link rel=preload as=image href=lqip_my_image.jpg fetchpriority=high>
The method used works and for the most-part is transparent to the user and not dependent upon browser javascript support.
When used with the single-tag mode of operation, JCOGS Images' lazy-loading system is completely compatible with its responsive image options delivered via the srcset= option.
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 Pro during template parsing and will cause it also to add a preload instruction to the HTML <header> section.
It should be noted, however, that due to the complexity of processing associated with the generation of 'srcset' output, currently it is not possible to use this approach to enable lazy loading of images via tag-pair output when the srcset parameter is also included in the Image tag parameters.
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.
Face Detection Technology
JCOGS Image Pro includes sophisticated face detection technology that automatically identifies human faces in images. This capability powers face-aware cropping and enables face-detection filters for privacy protection. The system uses the HAARPHP library implementing the Viola-Jones algorithm, providing universal PHP compatibility without requiring server extensions.
How Face Detection Works
Pro's face detection uses Haar Cascade Classifiers, a machine learning technique that scans images at multiple scales looking for facial features. The system has been trained on thousands of face images to recognize patterns characteristic of frontal human faces.
Detection Process
The algorithm scans the image using a sliding window that starts at different scales. At each position, it evaluates whether the region contains face-like patterns. Multiple overlapping detections are merged into final face regions with coordinates and dimensions.
Quality Modes
JCOGS Image Pro provides three quality modes that balance speed and accuracy. Choose the appropriate mode based on your specific requirements.
Fast Mode: Optimized for speed using a simpler cascade with fewer detection stages and Canny edge pruning. Processing time typically 100-200ms per image. Accuracy approximately 75-80%, suitable for batch operations and real-time processing where speed is critical.
Balanced Mode (Default): Standard cascade with good compromise between speed and accuracy. Processing time typically 200-350ms per image. Accuracy approximately 80-85%, recommended for most general-purpose applications. This is the default mode when face_detection_quality parameter is not specified.
Accurate Mode: Comprehensive cascade with more detection stages and thorough search parameters. Processing time typically 400-700ms per image. Accuracy approximately 85-92%, ideal when face detection accuracy is critical or images have challenging conditions (difficult lighting, small faces, group photos).
Integration with Image Processing
Face-Detect Crop Mode
The primary use of face detection is crop="face_detect", which automatically positions the crop area to include detected faces. When multiple faces are found, the crop encompasses all faces. If no faces are detected, the system falls back to center cropping.
Control quality mode with: face_detection_quality="fast|balanced|accurate"
Fine-tune detection sensitivity with: face_detect_sensitivity="1-9" (default 3 for crops)
Adjust crop margin with: face_crop_margin="20px" (space around detected faces)
Face Detection Filters
The face_detect filter visually overlays bounding boxes on detected faces, useful for testing and diagnostics. Combine with quality modes and debug output to optimize detection parameters for your specific image set.
Performance Characteristics
Processing Times
Face detection processing time varies with image size, complexity, and quality mode. Typical 800×600px image processing times:
- Fast Mode: 100-200ms (3-5× faster than balanced)
- Balanced Mode: 200-350ms (baseline performance)
- Accurate Mode: 400-700ms (20-30% slower, improved accuracy)
Usage Notes
Quality mode selection guide
Use Fast Mode when:
- Processing large batches of images (hundreds or thousands)
- Generating user-uploaded content thumbnails in real-time
- Speed is more important than perfect accuracy
- Images have clear, prominent faces with good lighting
- Creating preview images or temporary crops
- Resource constraints require fast processing
Use Balanced Mode when:
- Standard content management scenarios (this is the default)
- Member avatars, author photos, team member images
- Mixed image quality and lighting conditions
- You want "good enough" accuracy without performance penalty
- Processing time is acceptable (under 500ms)
- Most general-purpose face-aware cropping needs
Use Accurate Mode when:
- Professional photography or portfolio sites
- Accuracy is critical to application success
- Images have challenging conditions (group photos, small faces, varied lighting)
- Processing time is acceptable (under 1 second per image)
- Privacy filters where missing a face has consequences
- Batch processing overnight where time isn't critical
Remember: All modes cache results. First request pays processing cost, subsequent requests use cached coordinates with negligible overhead. Choose quality mode based on first-request requirements.
Usage Notes
Common use cases and integration examples
Use Case 1: Member Avatar Generation
Automatically crop uploaded profile photos to face-centered squares:
width="200" height="200" crop="face_detect" face_detection_quality="fast" face_crop_margin="30px"
Fast mode is sufficient because member photos typically have clear, centered faces. 30px margin provides breathing room around face edges.
Use Case 2: Team Directory with Varied Photos
Process mixed-quality team photos with consistent face-centered crops:
width="400" height="400" crop="face_detect" face_detection_quality="balanced" face_crop_margin="20px"
Balanced mode handles varying lighting and photo quality. Some team photos are professional, others are casual snapshots.
Use Case 3: Professional Portfolio Headshots
High-quality professional portraits where accuracy is paramount:
width="800" height="800" crop="face_detect" face_detection_quality="accurate" face_crop_margin="100px" quality="95"
Accurate mode with generous margin and high JPEG quality. Professional photography demands highest standards.
Use Case 4: Privacy Protection Filters
Apply blur or pixelation to detected faces for privacy:
filter="face_detect" face_detection_quality="accurate"
When privacy is the goal, missing a face has serious consequences. Accurate mode ensures comprehensive detection.
Use Case 5: Batch Thumbnail Generation
Process 500 product photos showing people using products:
width="300" height="300" crop="face_detect" face_detection_quality="fast"
Fast mode with caching completes batch in reasonable time. Secondary images don't demand perfect accuracy.
Usage Notes
Combining quality modes with sensitivity parameter
The face_detection_quality and face_detect_sensitivity parameters work together for fine-grained control. Quality mode affects algorithm complexity, sensitivity affects detection threshold.
Understanding sensitivity values (1-9):
Low sensitivity (1-3): Only detect very confident face matches. Reduces false positives but may miss subtle or partially obscured faces. Default is 3 for crop operations.
Medium sensitivity (4-6): Balanced approach accepting reasonably confident detections. Default is 5 for filter operations. Good for general use.
High sensitivity (7-9): Detect more potential faces including ambiguous matches. Increases true positives but also false positives. Use for challenging images where missing faces is worse than occasional false detection.
Effective combinations:
Fast + Low Sensitivity (fast, 1-2): Quickest processing, only obvious faces detected. Good for clear portraits in batch operations.
Balanced + Medium Sensitivity (balanced, 3-5): Default combination. Best general-purpose settings for most applications.
Accurate + High Sensitivity (accurate, 7-9): Maximum detection capability. Catches difficult faces but takes longest. Use when comprehensiveness is critical.
Balanced + High Sensitivity (balanced, 7-8): Good compromise for group photos. More thorough than default without full accurate mode overhead.
Accurate + Low Sensitivity (accurate, 1-2): High-precision mode. Only detects very confident faces with thorough algorithm. Minimizes false positives.
Example: crop="face_detect" face_detection_quality="accurate" face_detect_sensitivity="7"
Usage Notes
Performance optimization strategies
Cache Utilization:
Face detection results are automatically cached with processed images. The same source image with identical parameters (including quality mode and sensitivity) retrieves cached coordinates without re-detection. First request pays processing cost, subsequent requests are instantaneous.
Quality Mode Per Context:
Different contexts within your site can use different quality modes. User-generated thumbnails use fast mode, featured portfolio images use accurate mode, editorial content uses balanced mode. Each context generates separate cached images.
Pipeline Order Optimization:
JCOGS Image Pro automatically runs face detection before smart-scale resizing. Detection happens on full-resolution source images, providing best accuracy. Coordinates are scaled appropriately during subsequent transformations.
Batch Processing Strategy:
When processing large batches, use fast mode for initial generation. If results are unsatisfactory for specific images, re-process those individually with balanced or accurate mode. Pro's caching ensures you never process the same parameters twice.
Preload Strategy:
For high-traffic pages with face-detected images, warm the cache during off-peak hours. Use a script or add-on to request all face-detect variations, ensuring live traffic hits warm cache.
Resource Considerations:
Face detection is CPU-intensive. On shared hosting or resource-constrained servers, fast mode prevents request timeouts. On dedicated servers with ample resources, accurate mode is viable for production use.
Usage Notes
Limitations and best practices
Frontal Face Limitation:
The cascade classifiers are optimized for frontal and near-frontal face views. Profile views (side-facing), extreme angles, or back-of-head shots have reduced detection rates. For best results, use images where faces are oriented toward the camera.
Lighting Requirements:
Detection works best with moderate, even lighting. Extreme overexposure (blown-out highlights) or underexposure (dark shadows) reduce accuracy. Harsh shadows across faces can confuse the algorithm. Balanced Mode and Accurate Mode include preprocessing that helps with lighting challenges.
Face Size Considerations:
Faces should comprise at least 15-20% of the image area for reliable detection. Very small faces (distant subjects) or tightly cropped faces exceeding frame boundaries have lower detection rates. The algorithm searches at multiple scales, but extremely small faces may be missed.
Occlusion Handling:
Partially obscured faces (sunglasses, hands, objects) reduce detection confidence. Full occlusion (scarves covering lower face, hair across eyes) significantly impacts accuracy. For best results, use images with clearly visible facial features.
Multiple Face Handling:
When multiple faces are detected, crop="face_detect" encompasses all detected faces in the crop area. This works well for couples or small groups. Very large groups may result in distant, small faces in the final crop. Consider adjusting face_crop_margin for multi-face scenarios.
Fallback Behavior:
If no faces are detected, the system falls back to center cropping. This prevents broken images but may not produce ideal results. Use the face_detect filter to visualize detection before committing to crop settings. Debug mode shows whether faces were detected.
Testing Recommendations:
Always test face detection on representative image samples before deploying to production. Use debug="yes" to see detection details. Use filter="face_detect" to visualize detected regions. Different image sources (professional photography, user uploads, stock photos) may require different quality settings.
Usage Notes
Debugging face detection with visual tools
JCOGS Image Pro provides several debugging tools to troubleshoot face detection issues and optimize quality settings.
Face Detect Filter:
The face_detect filter draws green bounding boxes around detected face regions. This visual feedback shows exactly what the algorithm detected before applying crops or filters.
Usage: filter="face_detect" face_detection_quality="balanced" debug="yes"
Green boxes indicate the detection bounding box collection (encompassing all faces). Yellow boxes show individual face regions. Compare results across quality modes to see how detection changes.
Debug Output:
Adding debug="yes" to your image tag displays comprehensive processing information:
- Quality mode used (fast/balanced/accurate)
- Detection processing time in milliseconds
- Number of faces detected
- Face coordinates (x, y, width, height) for each detection
- Whether cached coordinates were used or new detection ran
- Sensitivity value applied
- Fallback information if no faces detected
Debug output appears as HTML comments in source code. View page source to examine detection details.
Quality Mode Comparison:
Create test templates showing the same image with different quality modes side-by-side. Process once with face_detection_quality="fast", once with balanced, once with accurate. Compare detection accuracy and processing times to choose optimal settings for your image collection.
Sensitivity Testing:
Test different sensitivity values (1, 3, 5, 7, 9) with the same quality mode. Low sensitivity might miss subtle faces, high sensitivity might create false positives. Find the sweet spot for your specific images.
Processing Time Analysis:
Debug output includes processing times. If detection takes excessive time (>1 second), consider faster quality mode or smaller source images. First request always takes longer due to detection and caching. Subsequent requests show cached performance (near-zero).
Usage Notes
Technology architecture and HAARPHP implementation
JCOGS Image Pro uses HAARPHP, a pure PHP implementation of the Viola-Jones face detection algorithm using Haar Cascade Classifiers. This architecture provides universal compatibility without requiring server extensions.
Why HAARPHP:
Unlike OpenCV-based solutions requiring PHP extensions and compiled libraries, HAARPHP works on any PHP 7.4+ environment. Shared hosting, cloud hosting, and managed servers all support face detection without special configuration. This architectural decision ensures maximum compatibility with existing JCOGS Image user base.
Haar Cascade Classifiers:
The detection system uses pre-trained machine learning models (cascades) that recognize facial patterns. Fast mode uses a 20-stage cascade optimized for speed. Balanced mode uses a 22-stage cascade balancing performance. Accurate mode uses a 25-stage comprehensive cascade maximizing accuracy.
Viola-Jones Algorithm:
This algorithm scans images using rectangular feature comparisons at multiple scales. It's exceptionally fast for a pure PHP implementation, processing typical images in 100-700ms depending on mode. The algorithm has been the industry standard for face detection since 2001, proven reliable across millions of applications.
Provider Architecture:
Face detection in Pro uses a provider system allowing future expansion. Current built-in provider uses HAARPHP (local detection). Future companion add-ons could add cloud-based providers (AWS Rekognition, Google Cloud Vision, Azure Face API) with 95%+ accuracy. The provider system automatically selects the best available provider based on priority.
Performance vs Cloud Solutions:
HAARPHP accuracy (75-92% depending on mode) is lower than cloud AI services (95-98%). However, cloud services require API credentials, incur per-request costs, raise privacy concerns (images sent to third parties), and depend on external availability. For most content management applications, local detection provides adequate accuracy without dependencies or ongoing costs.
Processing Optimizations:
Pro includes several optimizations over stock HAARPHP: Canny edge pruning in fast mode (2-3× speedup), intelligent downsampling for fallback detection, cascade caching in memory, adaptive search parameters based on image characteristics, and integration with Pro's two-level caching system.
Future Enhancements:
Potential future improvements include profile face detection (side views) in accurate mode, multi-scale consensus for improved accuracy, adaptive preprocessing based on image analysis, and intelligent fallback strategies when no faces detected. The provider architecture makes these enhancements possible without breaking existing implementations.
Hooks
JCOGS Image Pro provides three hooks that are functionally equivalent to the hooks offered by CE Image. The hooks offered are:
| CE Image Hook | JCOGS Image Hook | Description |
|---|---|---|
| ce_img_start | jcogs_img_start | Called when image processing starts. Accepts no data. Returns no data. |
| ce_img_pre_parse | jcogs_img_pre_parse | Called when image processing is complete but before any tagdata from the calling tag-pair is parsed prior to its return to the template. The hook thus allows you to manipulate the image variables before they are returned to the template. The following data is passed by the hook when called: The $tagdata must be returned to the hook when your local processing of it is completed. |
| ce_img_saved | jcogs_img_saved | Called when an image is saved. The hook returns: $this->path_final: The local path on the server to the saved image. $type: The image type, which will be one of the following: ‘bmp’, ‘gif’, ‘jpg’, ‘jpeg’, 'png', 'webp' |
Image Caching
JCOGS Image Pro uses a powerful image caching system to store copies of processed images on the server. When image caching is enabled and when possible, JCOGS Image Pro will re-use a cached copy of processed image.
For most users, enabling JCOGS Image Pro caching will significantly improve the speed of response for your site.
JCOGS Image Pro has a number of high-performance features:
- fine-grained control over caching - set caching strategies on a per-image basis
- support for variable cache-durations - set cache lives on a per-image or system wide basis
- reliable - a tight managed association between source image, processing options and cached copy ensures that you always get the right image back from the cache
- unified cache - all images are normally stored in a single folder which means that regardless of how many templates a processed appears within the same cached copy will be used each tim - saving on storage and processing time
- auto-cache maintenance features - JCOGS Image Pro provides tools to automatically remove redundant images from the cache
JCOGS Image Pro uses a carefully constructed modified filename for processed images that includes the original file name, and additional elements that help it track the image processing options chosen when the image was created and also the caching lifetime chosen for the image.
Usage Notes
Use with other caching systems
JCOGS Image Pro's caching system only updates images in its cache when EE processes a template that contains JCOGS Image Pro tags and if finds that the cache does not contain a copy of the processed image, or if the cache-life of a copy of the processed image requested has expired. When you are using either quasi static caching (e.g. EE's Template Caching) or fully static caching when a page in that caching system is requested EE may not notify JCOGS Image Pro that the image has been requested, and so even if the images in JCOGS Image Pro's cache have expired they will not be deleted / recreated until the next time EE re-processes the relevant templates. Under such circumstances the cache duration settings used for an image will not always have the effect expected, and enabling the JCOGS Image Pro cache auto-management feature may produce unhelpful results.
Image Formats
Source Images
JCOGS Image Pro can work with source images in all of the GD2 supported image formats (see notes on this in Processed Images below), plus it can also read HEIC images and has limited support for SVG and animated GIF format source images.
Processed Images
The format options available for processed images are determined primarily by the abilities of the php image processing library used on the server running the EE instance.
JCOGS Image Pro actively checks what formats are supported by the server and only makes those available.
A list of the available processed image formats is available on the JCOGS Image Pro Control Panel settings page in the drop-down for ‘Default Image Format’ (which also ensures that the Default Image Format is always one that can be processed by the server!).
If you specify an image format in a JCOGS Image Pro tag that is not supported by the server, JCOGS Image will use the Default Image Format to encode the image instead.
For GD2 (the default library used by JCOGS Image Pro) commonly available formats include:
extension | image format |
|---|---|
avif | |
bmp | Windows bitmap format |
gif | Graphics Interchange Format |
jpeg/jpg | JPEG image format |
png | Portable Network Graphics |
webp | Webp |
For an image to be seen in a browser it is also important that the browser viewing the web page also supports the image format chosen. Where possible, when processing an image JCOGS Image Pro actively checks that the current browser is able to display the format chosen; if the browser would not be able to display the image format chosen JCOGS Image Pro substitutes a format that is supported both by the server and the browser (usually JPG).
JCOGS Image Pro offers limited support for handling SVG files and for animated GIF files - effectively both of these image types are passed through the add-on unchanged, but this feature allows them to be included in template workflows, and to benefit from JCOGS Image's image sizing and advanced cache management facilities. SVG Files are also ‘sanitised’ as part of this processing.
The choice of which image formats to use when is a complex discussion area, and outside the scope of this manual to consider.
Transparency
Not all image formats support transparency. Where possible transparency in images is preserved by JCOGS Image Pro during processing, but for transparency to be maintained in a processed image it is also important to make sure that the 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 an appropriate format either in the save_type= parameter in your tag, or as the Default Image Format.
Please note also that 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.
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.
JCOGS Image Pro offers both lossy and lossless compression options for these image formats (webp, png), however it is worth noting that this facility depends on support for these operations being available in the php libraries JCOGS Image Pro uses: for example, saving lossless webp images requires the server to be running php 8.1 or better.
Image Optimisation
A variety of utilities offer options to ‘optimise’ images of some image formats (most notably images of PNG or JPG type). ‘Optimisation’ generate similar looking images to the source, but with a smaller filesize. Promotional literature for the various image optimisation routines available often note that dramatic file sze reductions can be obtained, particularly for PNG images. The saving in file size coming from usually the ommission of ‘redundant' data from the source image. However, to allow maniuplation of an optimised image, these optimisations usually have to be reversed.
JCOGS Image Pro is able to work with most ‘optimised’ images, but does not save images back to their optimised state.
The tools used by libraries to optimise images typically are not included in standard web server builds, and so it is not easy for JCOGS Image Pro to include ‘optimisation’ steps within its core feature set (though such will be considered in some future update).
If you are using JCOGS Image Pro on a regular server then JCOGS Image Pro will automatically substitute an image format of that the user's browser can view should your site be viewed by a browser not able to handle webp images. If you are using JCOGS Image Pro on a server with a static cache - where JCOGS Image Pro's auto-substitution tools will not work - define your images using the HTML <picture> tag with web as the main image, with a jpg or png alternative image specified in a <source> declaration.
Usage Notes
Webp - better than optimised PNG
In our limited testing we find that the filesize saving achieved by PNG optimisers while dramatic (up to 50%) is small compared to the saving achieved by moving a PNG to WEBP format (up to 75%). So our recommendation for now is that if minimisation of image filesize is critical to your application, consider using webp as the default image format.
Named Attributes System
JCOGS Image Pro introduces a named attributes system for composite parameters, providing a self-documenting format that is easier to read, write, and maintain than traditional positional syntax. This system maintains full backward compatibility with the legacy positional format used in JCOGS Image.
Understanding Named Attributes
Named attributes use descriptive names for each parameter component, making complex parameter strings immediately understandable. Instead of memorizing positional order, you specify exactly what each value represents.
Positional Format (Legacy): Values must appear in exact order, requiring documentation to interpret.
Named Format (Pro): Each value is labeled with its purpose, self-documenting the parameter string.
Format Comparison Example
Legacy Positional: watermark="/media/logo.png|0,0|100|center,center|0,0|0"
Requires documentation to understand: "What does the first 0,0 mean? What's 100 for? Which center is horizontal?"
Pro Named: watermark="watermark_src:/media/logo.png|watermark_min_width:0|watermark_min_height:0|watermark_opacity:100|watermark_position_h:center|watermark_position_v:center|watermark_offset_x:0|watermark_offset_y:0|watermark_rotation:0"
Self-documenting: Each component clearly identifies its purpose.
Supported Composite Parameters
Six composite parameters in JCOGS Image Pro support the named attributes system:
Text Parameter
Supports 21 named sub-parameters including text content, font size, colors, positioning, shadow effects, background, rotation, and alignment. Example: text="text_content:Hello|text_font_size:24px|text_font_color:#FFFFFF|text_align_h:left|text_align_v:top"
Crop Parameter
Supports 6 named sub-parameters for crop mode, focus points, offsets, and smart scaling. Example: crop="crop_mode:yes|crop_focus_h:center|crop_focus_v:center|crop_offset_x:0|crop_offset_y:0|crop_smart_scaling:yes"
Watermark Parameter
Supports 11 named sub-parameters for source image, dimensions, opacity, positioning, offsets, and rotation. Example: watermark="watermark_src:/path/logo.png|watermark_opacity:80|watermark_position_h:right|watermark_position_v:bottom"
Border Parameter
Supports 2 named sub-parameters for border width and color. Example: border="border_width:5|border_color:rgba(30,40,50,0.75)"
Reflection Parameter
Supports 4 named sub-parameters for gap, opacity range, and reflection height. Example: reflection="reflection_gap:10|reflection_start_opacity:70|reflection_end_opacity:30|reflection_height:40%"
Rounded Corners Parameter
Supports 10 named sub-parameters (5 corners × 2 attributes: radius and color). Example: rounded_corners="all:20px|all_color:#FFF|tl:30"
Key Benefits of Named Attributes
Order Independence
Named attributes can be specified in any order. watermark="watermark_opacity:80|watermark_src:/logo.png" is equivalent to watermark="watermark_src:/logo.png|watermark_opacity:80". This flexibility eliminates errors caused by incorrect positional ordering.
Partial Specification
Specify only the parameters you need to change. Unspecified parameters automatically use default values. Example: watermark="watermark_src:/logo.png|watermark_position_h:right" uses defaults for all other watermark settings.
Self-Documentation
Parameter strings become self-explanatory. Template code with named attributes is maintainable without constant reference to documentation, especially important for complex parameters with many sub-components.
Backward Compatibility
The system automatically detects and correctly processes both named and positional formats. Existing templates using positional format continue working without modification. New templates can adopt named format for improved clarity.
Usage Notes
When to use named attributes vs positional format
Use named attributes when:
- Creating new templates or presets from scratch
- Working with complex composite parameters (especially text and watermark)
- Parameters will be maintained by multiple developers
- Template readability and maintainability are priorities
- You're specifying only a subset of available sub-parameters
- Parameter order is difficult to remember
Positional format remains appropriate when:
- Maintaining existing templates that already use positional syntax
- Minimizing parameter string length is critical
- Simple parameters with few components (e.g., border with just width and color)
- You're comfortable with the positional order and use it frequently
Remember: Both formats work identically. The choice is purely about code readability and maintenance preferences. JCOGS Image Pro automatically handles both formats transparently.
Usage Notes
Converting from positional to named format
Converting existing positional parameters to named format improves template maintainability. Follow this systematic approach:
Step 1: Identify the parameter type - Determine which composite parameter you're converting (text, crop, watermark, border, reflection, rounded_corners).
Step 2: Look up the positional order - Refer to the parameter documentation to understand what each positional value represents.
Step 3: Map values to names - Create named attribute pairs for each non-default value. Skip values that match defaults.
Step 4: Test thoroughly - Verify the converted parameter produces identical output to the original positional version.
Conversion Example - Watermark Parameter:
Original positional:
watermark="/media/watermarks/logo.png|300,200|80|right,bottom|10,-5|45"
Position mapping:
- Position 0:
/media/watermarks/logo.png→watermark_src:/media/watermarks/logo.png - Position 1:
300,200→watermark_min_width:300|watermark_min_height:200 - Position 2:
80→watermark_opacity:80 - Position 3:
right,bottom→watermark_position_h:right|watermark_position_v:bottom - Position 4:
10,-5→watermark_offset_x:10|watermark_offset_y:-5 - Position 5:
45→watermark_rotation:45
Converted named format:
watermark="watermark_src:/media/watermarks/logo.png|watermark_min_width:300|watermark_min_height:200|watermark_opacity:80|watermark_position_h:right|watermark_position_v:bottom|watermark_offset_x:10|watermark_offset_y:-5|watermark_rotation:45"
Note how the named format can be reordered for logical grouping without affecting functionality.
Usage Notes
Automatic preset conversion and Control Panel integration
JCOGS Image Pro's Control Panel automatically upgrades presets from positional to named format when you edit and save them. This seamless conversion requires no manual intervention.
How automatic conversion works:
When you open a preset with positional parameters in the Control Panel, the system detects the format and correctly parses values. The parameter edit form displays individual fields for each sub-parameter. When you save, JCOGS Image Pro automatically outputs the named format. Your preset is upgraded without losing any settings.
Control Panel parameter editing workflow:
- Navigate to the preset editor in JCOGS Image Pro Control Panel
- Select a parameter to edit (e.g., watermark, text, crop)
- System displays multi-field form with separate inputs for each sub-parameter
- Modify values using intuitive form fields (text inputs, dropdowns, color pickers)
- Click Save - parameter is automatically formatted as named attributes
- Named format is stored in preset and used for all subsequent loads
Benefits of Control Panel integration:
- No need to memorize complex parameter syntax
- Visual form fields with descriptions and placeholders guide you
- Validation happens per field, not per complex string
- Color pickers, dropdowns, and other UI controls simplify complex parameters
- Automatic format conversion means no migration work required
This integration makes named attributes the default for all Control Panel parameter editing, while templates continue supporting both formats for maximum flexibility.
Usage Notes
Default value behavior and partial parameter specification
Named attributes excel at partial parameter specification. Specify only the sub-parameters you want to change from defaults, and the system automatically fills in sensible defaults for everything else.
Minimal watermark example:
watermark="watermark_src:/media/logo.png"
This minimal specification automatically uses these defaults:
- watermark_min_width:0 (no minimum width constraint)
- watermark_min_height:0 (no minimum height constraint)
- watermark_opacity:100 (fully opaque)
- watermark_position_h:center (centered horizontally)
- watermark_position_v:center (centered vertically)
- watermark_offset_x:0 (no horizontal offset)
- watermark_offset_y:0 (no vertical offset)
- watermark_rotation:0 (no rotation)
Progressive refinement pattern:
Start with minimal parameters and add only what you need:
Step 1: watermark="watermark_src:/logo.png" - Adds centered watermark
Step 2: watermark="watermark_src:/logo.png|watermark_position_h:right" - Moves to right side
Step 3: watermark="watermark_src:/logo.png|watermark_position_h:right|watermark_position_v:bottom" - Places in bottom-right corner
Step 4: watermark="watermark_src:/logo.png|watermark_position_h:right|watermark_position_v:bottom|watermark_offset_x:-10|watermark_offset_y:-10" - Adds 10px padding from edges
This progressive approach makes parameter configuration intuitive and reduces errors from specifying unnecessary values.
Default values for each composite parameter:
Each parameter package defines sensible defaults appropriate for its function. Consult individual parameter documentation for complete default value listings. Common patterns include 0 for offsets, 100 for opacity, center for positioning, and empty strings for optional paths.
Usage Notes
Validation advantages of named attributes
Named attributes enable sophisticated per-field validation that isn't possible with positional formats. The system validates each named sub-parameter independently with parameter-specific rules.
Enhanced validation capabilities:
Type-specific validation: Numeric fields reject non-numeric input. Color fields validate hex codes and CSS formats. Enumerated fields (like crop_focus_h) only accept defined values (left, center, right).
Range validation: Opacity fields enforce 0-100 range. Percentage fields validate format. Coordinate fields check for valid dimension specifications.
Dependency validation: Some sub-parameters depend on others. Named format allows validation rules to reference other named fields. Example: watermark_min_height is only meaningful when watermark_src is specified.
Detailed error messages: When validation fails, error messages identify the specific sub-parameter name. Instead of "Invalid parameter at position 3", you see "Invalid value for watermark_opacity: must be between 0 and 100".
Example validation scenarios:
Invalid opacity value:
watermark="watermark_src:/logo.png|watermark_opacity:150"
Error: "watermark_opacity must be between 0 and 100. Received: 150"
Invalid position value:
crop="crop_mode:yes|crop_focus_h:middle"
Error: "crop_focus_h must be one of: left, center, right. Received: middle"
Invalid color format:
border="border_width:5|border_color:#GGGGGG"
Error: "border_color is not a valid color. Must be hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), or color name. Received: #GGGGGG"
This validation infrastructure improves developer experience by catching configuration errors early with actionable error messages.
Usage Notes
Pro-exclusive feature: Named attributes not available in Legacy
The named attributes system is exclusive to JCOGS Image Pro and represents a significant enhancement over the Legacy version. This architectural improvement is part of Pro's sophisticated parameter package system.
Why named attributes are Pro-only:
Named attributes require the parameter package architecture introduced in JCOGS Image Pro v2.0.0. This system includes format detection, automatic conversion, validation frameworks, and Control Panel integration. Backporting to Legacy would require substantial refactoring incompatible with Legacy's architecture.
Migration implications:
When migrating from JCOGS Image Legacy to Pro, your existing templates continue working without modification. Positional format remains fully supported. Once migrated, you gain the option to adopt named attributes for new development while maintaining positional format where appropriate.
Preset compatibility:
Presets created in Legacy using positional format work correctly in Pro. When you edit these presets in the Pro Control Panel, they're automatically upgraded to named format on save. This one-way conversion is safe and reversible (Pro always reads both formats).
Template migration strategy:
After migrating to Pro, consider converting complex parameters to named format during maintenance cycles. Focus on parameters with many sub-components (text, watermark) where self-documentation provides maximum benefit. Simple parameters (border, reflection) may not need conversion if positional format is already clear.
Documentation differences:
Pro parameter documentation includes both positional and named format syntax. Legacy documentation only shows positional format. When working with Pro, reference the Pro documentation for complete named attributes coverage, including sub-parameter names, default values, and validation rules.
Nesting Tags
Most operations that you might want to carry out on an image source can be completed by adding parameters to a single JCOGS Image Pro tag: in particular Filters are applied sequentially in the order you add them to the filter parameter. Yet sometimes it is useful to apply an transformation to an already transformed image.
To support this needs JCOGS Image Pro supports the ‘nesting’ of tags - putting one JCOGS Image Pro tag ‘within’ another, and using the output of the ‘inner' tag as the source image for the operations of the outer tag.
Here is a pair of tags being applied to a single image source - the output of the exp:jcogs_img_pro:single tag is being used as the source for the exp:jcogs_img_pro:image tag:
The effect of these two ‘nested’ tags is to add two borders to the original image, and to resize the source image so that it is (before the borders are added) 300px wide.
In addition to this kind of nesting, JCOGS Image Pro also supports the inclusion of Image tags within JCOGS Image Pair tags.
For more complex / deep nesting you should use a tag suffix to differentiate nested levels of JCOGS Image Pro tags - this approach would theoretically allow you to nest images as many times as you would like, but it is important to note that such deep nesting is not recommended for performance reasons.
Variable Prefixing
Using a tag suffix with a Pair tag also enables the use of automatic variable prefixing. Operation is simple - if you append a suffix to your JCOGS Image Pro tag, variables produced by the tag are accessed by putting the same prefix followed by a colon character before the variable name. For example if we recode the example above using this approach we get something like:
If you plan to ‘nest’ JCOGS Image tags within your templates there are a few of things to remember:
Parse="inward" if you want enclosed tags to be processed first
EE's template parser normally does a good job of working out the correct sequence to work through the tags within a template, but when the tags are calls to the same add-on/method sometimes this does not work so well. For JCOGS Image Pro, if you want to ensure that an “inner” tag is processed first, it helps to put the EE parameter parse='inward' into the parameter list for the ‘outer’ tag to ensure that processing of the ‘inner’ tag is completed before the processing of the outer tag begins.
Use different method names and / or tag-pairs and/or add a variable suffix to sidestep EE parsing issues
Sometimes the EE template parser can get confused when you have more than one tag that can exist in both single-tag and tag-pair modes. Consider this example:
EE's template parser will get confused about which opening tag the {/exp:jcogs_img_pro:image} closing tag refers to - probably choosing the first tag as the opening one - which will lead to unexpected / unwanted results. There are two ways to avoid this:
Always use closing tags - this option avoids the confusion, but keep in mind (for CE Image compatbility) tag-pairs intepret some parameters in a different way to single tag (for example the create_tag parameter)
Use different JCOGS Image Pro names to avoid the confusion - If you use a different method name for single tags to tag-pairs you can also avoid this parsing confusion. JCOGS Image Pro gives you the choice of three alternative names - image, single, and pair.
Usage Notes
Note: if you use the tag-pair form, remember that for this tag to generate any output you either need to specify some template variables between the tag pair, or add the parameter create_tag='yes' to the parameters for the outer tag.
Pass-through attributes and attribute consolidation
JCOGS Image Pro provides powerful options for ‘passing through’ HTML parameters to the finished HTML <img> tag (or other tags if you are using the tag-pair approach to build advanced HTML tags).
Any parameters included within a JCOGS Image Pro tag that are not valid JCOGS Image Pro parameters are collected up and added to the tag output - either as attributes included within a created <img> tag, or as the content of the {attributes} variable. This allows you to simply add any additional parameters you would like to include in the output <img> tag to those included to control the image processing.
For example:
will produce a tag of this form:
You can also include additional parameters to pass through to the output / attributes variable by:
- adding an attributes="" parameter to your tag - whatever is enclosed in this parameter is appended to the attributes variable output and / or included in the generated <img> tag
- enclosing attributes entries between a pair of JCOGS Image tags when you have also set create_tag="yes"
Including Image Variables in attributes parameter entries
By default if you include one or more Image Variables within your attributes entry these variables will be evaluated before the resulting tag is drawn to your web page. This feature allows you to include image specific information (such as filesize) within custom attributes in your generated tag. So for example this simple tag:
will produce an HTML tag similar to this
This feature can be disabled via the Enable expansion of Image Variables within attribute parameter text setting which can be found in Image's Advanced Settings panel.
Special handling for Class and Style attributes
Because you can specify additional attributes in several places it is possible for JCOGS image Pro to find multiple examples of attributes defined within your tag inputs. For class and style attributes (only) JCOGS Image Pro will collect and consolidate the content from multiple attributes and deliver just one class and one style tag that contains all of the applicable content - it will also attempt to remove duplicate style or class entries if there are any.
Sometimes it is not helpful for this class and style consolidation to happen - for example where for some reason you have enclosed multiple HTML elements within a JCOGS Image Pro tag-pair, each with its own class or style attributes. This consolidation function can be disabled on a tag by tag basis by adding the consolidate_class_style="no" parameter to a tag, or by disabling the Class / style attribute consolidation for tag-pair operation default setting - which can be found in the Advanced Settings panel.
Performance Optimisation
JCOGS Image Pro includes advanced performance optimization features designed to maximize caching efficiency and minimize processing overhead. At the center of this system is the Cache Threshold Optimizer, an automatic benchmarking tool that analyzes your cache characteristics and determines the optimal loading strategy for your specific environment.
Understanding Cache Loading Strategies
Image Pro uses two different strategies for loading the cache log into memory:
- Full Preload - Loads the entire cache log into memory at once (faster for small-to-medium caches)
- Incremental Loading - Loads cache entries on-demand as needed (better for large caches)
The optimal strategy depends on your cache size, server memory, and usage patterns. A cache with 500 entries performs best with full preload, while a cache with 50,000 entries benefits from incremental loading.
The Cache Threshold Optimizer
Rather than requiring you to manually tune this setting through trial and error, Image Pro includes an automatic benchmarking tool that scientifically determines the optimal threshold for your environment.
How It Works
The optimizer performs a series of benchmarks testing both loading strategies with your actual cache data:
- Warm Cache Test - Measures performance when cache data is already in memory (simulates repeated page loads)
- Cold Cache Test - Measures performance starting from empty memory (simulates first page load or cache clear)
- Analysis - Compares results across both strategies and calculates optimal threshold
- Recommendation - Presents findings with one-click application
The entire process takes 10-30 seconds and provides detailed performance metrics for both strategies.
Running the Optimizer
To run the Cache Threshold Optimizer:
- Navigate to: Add-Ons → JCOGS Image Pro → Cache Management
- Click the "Run Benchmark" button
- Wait for benchmarks to complete (10-30 seconds)
- Review the results and recommendation
- Click "Apply Recommended Setting" to activate
The optimizer displays detailed metrics including load times, memory usage, and performance differences between strategies.
Performance Metrics Explained
Warm Cache Performance
Warm cache metrics show performance when the cache log is already in memory (PHP opcache, repeated requests). This represents the most common scenario for production sites with steady traffic. Optimization here directly impacts user experience.
Cold Cache Performance
Cold cache metrics measure performance starting from empty memory (server restart, first request after deployment, cache invalidation). While less frequent, cold cache optimization ensures fast recovery after maintenance or deployment.
Memory Usage
The optimizer reports peak memory usage for each strategy. Full preload uses more memory upfront but may reduce overall memory churn. Incremental loading uses less initial memory but may allocate memory gradually throughout request processing.
Interpreting Results
The optimizer automatically interprets results and provides recommendations, but understanding the metrics helps you make informed decisions:
- Performance improvement >20% - Significant benefit, strongly recommended to apply
- Performance improvement 10-20% - Moderate benefit, recommended to apply
- Performance improvement 5-10% - Slight benefit, optional to apply
- Performance improvement <5% - Minimal difference, either strategy acceptable
Note: The optimizer considers both warm and cold cache performance, weighting warm cache more heavily as it represents typical production usage.
Usage Notes
When to run the optimizer
You should run the Cache Threshold Optimizer in the following situations:
- Initial setup: Run once after installing Image Pro to establish baseline performance
- After cache growth: Re-run when your cache has grown significantly (10x increase, 10,000+ new entries)
- After server changes: Re-run after PHP version upgrades, memory limit changes, or server hardware upgrades
- Performance troubleshooting: Run if you notice slower image processing or Control Panel page loads
- Periodic review: Consider running quarterly or bi-annually as part of regular maintenance
The optimizer is non-destructive and can be run as often as needed without affecting your cache data or site performance.
Usage Notes
Cache size and strategy selection
General guidelines for cache loading strategy selection:
- Small caches (0-1,000 entries): Full preload almost always optimal - fast load, minimal memory
- Medium caches (1,000-10,000 entries): Depends on entry size and server memory - run optimizer to determine
- Large caches (10,000-50,000 entries): Incremental loading often better - reduces initial memory allocation
- Very large caches (50,000+ entries): Incremental loading strongly recommended - full preload may exceed memory limits
These are rough guidelines. The optimizer provides precise recommendations for your specific environment.
Usage Notes
Performance vs. memory trade-offs
Understanding the trade-offs between loading strategies helps you make informed decisions if you choose to override optimizer recommendations:
Full Preload Benefits:
- Faster cache lookups (single array access)
- Lower query overhead (one database query vs. many)
- Better for high-traffic sites with many concurrent requests
- Consistent performance regardless of cache entry distribution
Full Preload Drawbacks:
- Higher initial memory allocation
- Slower first-request performance (must load entire cache)
- May exceed memory limits on shared hosting with very large caches
Incremental Loading Benefits:
- Lower initial memory footprint
- Faster startup (no preload delay)
- Scales better with extremely large caches
- Only loads entries actually needed for current request
Incremental Loading Drawbacks:
- More database queries (one per cache lookup)
- Slightly slower cache lookups (database query vs. array access)
- Performance varies based on cache entry distribution
The optimizer weighs these factors against your actual cache characteristics to provide optimal recommendations.
Usage Notes
Impact on Control Panel performance
The cache loading strategy affects Control Panel page load times, particularly the Cache Management page and preset editing interfaces:
- Full Preload: May cause slight delay when first loading CP pages after server restart, but subsequent page loads are very fast
- Incremental Loading: Consistent CP page load times regardless of cache size, but may be slower for cache-intensive operations
For sites where developers frequently access the Control Panel, optimizing for warm cache performance (typically full preload for medium caches) provides the best experience.
For sites where the Control Panel is accessed infrequently, cold cache performance becomes more important, potentially favoring incremental loading for large caches.
Usage Notes
Advanced: Manual threshold configuration
While the automatic optimizer is recommended, advanced users can manually configure the cache threshold via the Advanced Settings panel:
Location: Add-Ons → JCOGS Image Pro → Settings → Advanced Settings
Setting: "Cache preload threshold"
Values:
- 0 - Always use incremental loading (never preload)
- 1-999999 - Use full preload if cache entry count is below this threshold
- 999999 - Always use full preload (maximum threshold)
Manual configuration is useful for:
- Testing different strategies during development
- Enforcing specific strategies based on server policies
- Fine-tuning after initial optimizer run
Important: Manual configuration overrides optimizer recommendations. Re-running the optimizer will provide new recommendations but will not automatically apply them unless you click "Apply Recommended Setting."
Usage Notes
Pro-specific cache optimizations
In addition to the automatic threshold optimizer, Image Pro includes several Pro-specific cache optimizations not available in Legacy:
- Two-level caching: In-memory cache for active entries plus persistent database cache for long-term storage
- Request-level cache: Prevents duplicate database queries within single request (eliminates redundant SELECT operations)
- Batch operations: Groups multiple cache writes into single database transactions (reduces query overhead)
- Cache key optimization: Enhanced cache key generation includes dimensional parameters (fixes RC5 cache collision bug)
- Lazy placeholder fast path: Lazy loading placeholders available in fast path for cached images (RC6 enhancement)
- File manager field caching: Shared method eliminates duplicate field lookups (RC6 optimization - 80 lines of code removed)
These optimizations work automatically and do not require configuration. Combined with optimal threshold settings, they provide significantly better performance than Legacy:
- Warm cache: 83% faster than Legacy (typical)
- Cold cache: 6.8% faster than Legacy (typical)
- Control Panel: Up to 100% faster (when File Manager fields not used)
Usage Notes
Troubleshooting cache performance issues
If you experience slower than expected performance despite running the optimizer:
Check PHP memory limit: Ensure your PHP memory_limit is sufficient for your cache size. Full preload requires enough memory to hold all cache entries. Typical requirements:
- Small caches (0-1,000): 64-128MB sufficient
- Medium caches (1,000-10,000): 128-256MB recommended
- Large caches (10,000-50,000): 256-512MB recommended
- Very large caches (50,000+): 512MB-1GB+ may be needed
Verify cache consistency: Navigate to Cache Management and check cache statistics:
- Total entries should match expected cache size
- No excessive expired entries (run auto-maintenance if needed)
- Cache hit rate should be >80% for production sites
Consider cache cleanup: If you have many expired or orphaned entries, use the "Clear Expired" or "Clear All" functions in Cache Management, then re-run the optimizer with a clean cache.
Enable debug mode: For detailed performance analysis, enable debug mode and examine cache operation timings in debug output. This shows exactly which cache operations are taking longest.
Test with staging environment: If possible, replicate your cache to a staging environment and experiment with different thresholds to measure real-world impact before applying changes to production.
Understanding the JCOGS Image file-naming approach
Many questions are asked about how JCOGS Image Pro names its processed images. These notes explain a bit more about what is behind the approach used.
The Image file name has three components - all are important
Image names a processed image with a file name comprising three elements - the original file name followed by two hashes: one relating to the ‘cache duration’ assigned to the image and a second that relates to what transformations were done to the original image in order to generate it. Image does this so that when it pulls an image from the cache it can be sure that it pulls the correct one.
What is wrong with just using the original file name?
There are multiple site operation issues that arise from the “same as the original” naming strategy: all relate to how to handle the same source image appearing more than once within a site.
- Within a page
If different versions of the same image appears multiple times on the same page (e.g. a thumbnail and a hi-res version) and you use the ‘same name’ strategy then you will have a direct clash - the browser will get confused about which version of the image to use where. A common resolution for this is to rename one or other version of the image so both can co-exist on the same page… in which case you are implicitly moving away from the “same name as the original” strategy … in which case you might as well just use JCOGS Image Pro names and be done with the complication! - Across multiple pages
On large / complicate sites the same image may appear in multiple pages even if you only have one copy per page (and in multiple versions across those pages). On such sites the ’same as original’ naming approach becomes one that is almost unusable. You’ll be serving multiple different images all with the same name (which therefore cannot be saved in the same directory). To allow for this a common solution is ‘directory based’ caching - either ‘file tree based' (the one used by CE Image) which saves cached images in a tree structure that replicates the routing pattern used by the web server, or a ‘category based' approach (the one used by EE’s Files system) where you save multiple versions of the image in ’named’ directory folders within the primary cache directory. Both are potentially horrifically inefficient approaches - for example on a site where you have ‘dynamic routing’ (e.g. the second slug in the URI is based on a date, the third based on a user name) the ‘file tree’ based solution will ‘cache’ copies of all images against that specific URI pattern, even though it is improbable that the same URI will ever be called again: those cached images are generated and saved and never used again. Category based caching doesn’t know what versions of an image will be needed by which templates, and so typically (as in case of EE’s files system) preemptively generate all variants for all images ‘just in case’. Both of these variants suffer from issues relating to cache management - it is very difficult to ‘clear’ these caches since you have no easy way of knowing which files within the cache are ‘used’ or not - so mostly people just leave them there always and forever. Which is fine, until you need to update an image … clearly the processed image can be regenerated - but the caching system has no idea if that processed image has already been generated and saved in a different folder … so you end up doing lots of unnecessary image processing.
Is the JCOGS Image Pro caching approach any good?
The three element filenames are required by JCOGS Image Pro's ‘unified cache’ approach - all the images processed by the add-on for a site are stored in a single folder. The filenaming approach used makes it possible for each and every use instance of a specific transformation of a source image across the whole of a site to be served from the same single cached copy. If you have multiple variants of the same image, the naming convention allows you to keep them separate within the same folder. Because Image has the cache-life for an image available from the file name, it is possible for Image to manage the cache - periodically checking and clearing images that have expired. Similarly if Image is requested to generate a specific version of an image, it can easily check thanks to the third segment of the filename if that specific version has been made before and get it back from the cache if so. On large / image intensive sites the caching approach Image uses is both space efficient and highly performant.
Doesn’t the extra filename elements mess with Google Analytics?
No. The file naming approach was developed in the light of extensive consultations with SEO experts and others. These consultations noted three factors that indicate Image's processed file naming strategy will not harm a site's SEO rating:
- Because the pattern starts with the original filename, this information is not lost and can be used as a search basis in Google Search.
- Because the additional elements are hashes, so they do not in themselves lead to ‘false positive’ findings (as is case when you, for example, put actual image dimensions into the filename).
- Because most image naming is nonsense (IMG_078932.jpg) search engines have learned to use contextual information rather than file name information as the key determinant of how image information is indexed. So in a very real sense the search engines “don’t care” about filenames.
Specifying Colours
Several of the parameters used by JCOGS Image Pro require the specification of colours.
JCOGS Image Pro supports use of hex-code and CSS type #NaN and rgba() colour specification models and CSS Colour Names.
Hex-code format
Originally based on use of a hexadecimal triplet with each pair of digits relating to one of the R, G and B components of the web standard RGB colour model, the hex-code format has over time expanded to represent colours using three, four, six or eight digit hexadecimal numbers.
JCOGS Image will accept any valid version of the hex-code format in any colour parameter - adding a leading # if one is omitted:
- Three-digit and four-digit hex codes are converted to six-digit and eight-digit hex codes before processing by duplicating each value - so #rgb → #rrggbb, and #rgba → #rrggbbaa.
- Eight digit hex codes are converted into six digit hex codes by removing the last two digits, which in turn are converted into an
opacityvalue for the colour being specified. - Six digit hex codes are converted into the RGB colour model by expanding the hex value pairs into equivalent integers in range 0-255 to give three integer values (one for R, one for G, one for B).
CSS #NaN and rgba() format
JCOGS Image Pro will accept colours specified in either the #NaN or rgba() formats used within CSS system.
Colour Names
JCOGS Image Pro will accept colours specified using the standard CSS colour names (e.g. 'yellow', 'azure' etc).
Mix and match…
You can use any combination of valid colour codes to specify colours, JCOGS Image Pro validates any colour specified by attempting to convert it into an rgba() type value, which is then used internally for all operations.
SVG Support
Passthrough Support for SVG
JCOGS Image Pro has a feature called SVG Passthrough Support.
The aim of this new feature is to enable SVG images to be functionally included within image workflows. JCOGS Image Pro provides for SVG images a limited (but useful) subset of JCOGS Image Pro's manipulation options:
- Image sizing
The desired width / height of processed SVG images can be set using all of the options available to regular images - set dimensions based on minimum or maximum values absolute values or through use of aspect ratios. - SVG santitizing
As noted above SVG images can be created that are the carriers of malicous content. JCOGS Image will automatically scan SVG images it reads for XSS type security issues and remove them: the sanitisation process used is a version of the highly regarded DOMPurify tool used in HTML environments. - Image caching
All of the standard options associated with the JCOGS Image cache are available to processed SVG files - in particular this provides a mechanism for remote image files to be cached on the server along with local image files.
The aim of this level of support is to remove the first obstacle to integrating SVG images more fully into your web design workflow. It is recognised that this is a small (but useful and important) step, but hopefully the first of a series of improvements that will ultimately lead to SVG images having access to most or all of the facilities provided by JCOGS Image Pro.
Unfortunately one facility that is not available currently for SVG images is converting them to other image formats.
The reasons for this cautious approach are primarily due to the nature of the SVG file format itself, and are largely outside the scope of JCOGS Image Pro itself to fix; however in so far as it is possible to resolve them, JCOGS Design is committed to finding the solutions required.
What are SVG files?
Scaleable Vector Graphics (SVG) is an XML based document format that allows the combination of a 2D vector graphics mark-up language with a simple page description language. SVG files need to be rendered by appropriate rendering systems for them to become visible as pictures. It has been in active development since 1999, but one that only recently has become a format that is widely used.
Although in some respects SVG represents an extraordinarily powerful approach to image definition, currently most practical uses of the standard appears to be define scalable vector images in a compact and portable format.
The core elements of the format were defined in a W3C standard in 2003 as SVG 1.1 - the current active version; SVG 2 has been in discussion since 2016 but as yet remains a draft proposal.
SVG image files do not directly contain an image - rather they contains instructions from which a rendered image can be constructed. These instructions can range from turtle-graphic style instructions for drawing vector based shapes to the expansion of base64 encoded images (which can be of any image format supported by the rendering browser) to the rendering of images obtained dynamically from remote web locations. In addition, the XML can contain information about transformations to apply to the rendered image - including rotations, applications of filters, dimension changes etc. Further, an SVG file can contain embedded CSS and Javascript instructions, and SIML animation instructions, offering scope for ‘dynamic’ image capabilities.
The very broad scope of elements that can be included in SVG files opens up a serious risk of malicious use that has lead to some calls for SVG files to be exclueded from (for example) email attachments, in particular SVG files can be vectors for XSS type malware.
Can I use them?
Widespread browser support for rendering some types of SVG images was largely in place by 2013, however SVG is a complicated standard and even by 2022 full support for all features is still not available. The key iOS platform gained the ability to render svg format images within <img> tags only in 2015.
Support for generating SVG images in popular graphics applications such as Adobe Illustrator is good, but again none currently support the full SVG 1.1 standard.
Implications for JCOGS Image Pro
JCOGS Image Pro is a tool for generating manipulated images for display within web pages and the focus of interest for the add-on is on helping its users work with any image format that can be deployed within a web page. Providing support for SVG has been a priority since the outset.
Unfortunately the complicated SVG 1.1 standard presents some challenges for JCOGS Image Pro (and other applications of a similar nature):
- The ‘image’ generated by an SVG needs to be rendered before it can be manipulated.
To (for example) change the image format of an SVG to (say) webp, JCOGS Image Pro needs to be able to generate a rendering of the image defined by the instructions in the SVG file. For users, this rendering is done by the browser, but rendered image may be affected by attributes of the local environment (for example the local dimensions of the image holder within browser), the platform it is being rendered on, and the local availability of some resources (such as True Type fonts).
- Competent SVG rendering engines that can be deployed within php are not yet available
Although work to develop SVG rendering and manipulation libraries that can be deployed within php is in progress, there has been limited success and currently native php mechanisms to manipulate SVGs are not available. In the interim php applications have addressed the the SVG rendering issue (where it is done at all) through the use use of external execution units; these external units are effectively limited function web browsers. In practical terms the approach adopted is to send the SVG definition to a remote process which effectively loads the XML in a browser, captures the rendered image generated and returns a acopy of this to the php process. Such rendering solutions are difficult to support, not particularly efficient or scalable, and incomplete (for example they do not flexibly address the environment / platform issue noted above).
- For SVG images, some transformation operations may be better delivered through editing the SVG format directly
Image resizing, cropping, and most other transformations can be delivered for SVG images through modifications of the XML specifying the ‘image’, likewise steps like adding borders, reflections, and overlay images and text can be achieved by applying SVG primitives to the XML file.
The consequence of these challenges is that full support of the SVG image formats by JCOGS Image Pro remains a future goal. Until then JCOGS Image Pro offers only limited support for the SVG image format.
Future developments
Work is underway to expand the range of maniuplation options available to include cropping, rotation and flipping: as php support for SVG grows the range of options that will work with SVGs will grow further.