Issue Fix for #2958 Transparent backgrounds on PNG images lost in dynamic media Urls #2978

khanmaroof · 2025-08-30T23:33:58Z

Q	A
Fixed Issues?	`Fixes #2958`
Patch: Bug Fix?
Minor: New Feature?	Yes
Major: Breaking Change?
Tests Added + Pass?	Yes
Documentation Provided	Yes (markdown)
Any Dependency Changes?
License	Apache License, Version 2.0

Conditional PNG Transparency Detection

Rather than applying fmt=png-alpha to all PNGs (which would cause significant performance issues), we can automatically detect which PNGs actually have transparency using existing DAM metadata.

Key Insight: dam:Bitsperpixel metadata reliably indicates PNG transparency:

32 bits = PNG with alpha channel (transparent) → Add fmt=png-alpha
24 bits = RGB PNG (opaque) → No format modifier needed
8 bits = Indexed PNG (opaque) → No format modifier needed

Implementation: Modify the Dynamic Media URL building logic in ImageImpl.java to automatically prepend fmt=png-alpha only when dam:Bitsperpixel = 32 for PNG assets.

Benefits:

✅ Preserves transparency automatically for transparent PNGs
✅ Maintains optimal performance for non-transparent PNGs
✅ Zero breaking changes - existing manual configurations still work
✅ Can be policy-controlled via autoPreservePngTransparency setting

This approach solves the transparency issue while completely avoiding the performance penalty since fmt=png-alpha is only applied when transparency actually exists.

…namic media URLs

vladbailescu

@khanmaroof , thank you for your contribution, this a really nice improvement!

I'm a bit concerned about usage of a non-public property from DAM (@actinium15 might be able to confirm this is the way forward).

I also have a few small comments around avoiding duplicating code.

vladbailescu · 2025-09-01T06:16:20Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v3/ImageImpl.java

+     * @param asset The DAM asset to check
+     * @return true if the PNG has transparency (32 bits), false otherwise
+     */
+    private boolean hasPngTransparency(Asset asset) {


Since Image (v3) implementation extends Image (v2), duplication of this method could be avoided by making it protected in the Image (v2) implementation.

@vladbailescu Fixed! I've refactored the code to eliminate duplication:

Made the hasPngTransparency() method protected in ImageImpl.java (v2)

Removed the duplicate implementation from ImageImpl.java (v3)

v3 now properly inherits the PNG transparency detection logic from v2

This maintains backward compatibility while reducing code duplication as you suggested.

vladbailescu · 2025-09-01T06:20:48Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

                }
+
+                // Auto-preserve PNG transparency if enabled and asset has transparency
+                boolean autoPreservePngTransparency = currentStyle.get(PN_DESIGN_AUTO_PRESERVE_PNG_TRANSPARENCY, false);


I would prefer to replace this block of code with a convenience method for evaluating the need of the modifier, it would be reusable in Image (v3) as well.

@vladbailescu Implemented! I've created a shouldApplyPngAlphaModifier(Asset asset) convenience method that:

Encapsulates both the configuration check (autoPreservePngTransparency setting) and transparency detection

Is protected so it can be inherited and reused by v3

Replaces the previous inline logic in both v2 and v3 implementations

The method provides a clean, reusable way to determine when the PNG alpha modifier should be applied.

vladbailescu · 2025-09-01T06:21:06Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

+                // Auto-preserve PNG transparency if enabled and asset has transparency
+                boolean autoPreservePngTransparency = currentStyle.get(PN_DESIGN_AUTO_PRESERVE_PNG_TRANSPARENCY, false);
+                if (autoPreservePngTransparency && hasPngTransparency(asset)) {
+                    String pngAlphaModifier = "fmt=png-alpha";


I would prefer we introduce a constant for the modifier.

@vladbailescu Done! I've added PNG_ALPHA_FORMAT_MODIFIER = "fmt=png-alpha" as a constant in the Image interface.

vladbailescu · 2025-09-01T06:23:27Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

+        }
+
+        String mimeType = asset.getMimeType();
+        if (!"image/png".equals(mimeType)) {


I would prefer we use a constant for the image/png, like https://developer.adobe.com/experience-manager/reference-materials/6-5/javadoc/com/day/cq/dam/commons/handler/StandardImageHandler.html#PNG1_MIMETYPE

@vladbailescu Updated! I've replaced the hardcoded "image/png" string with StandardImageHandler.PNG1_MIMETYPE.

vladbailescu · 2025-09-01T06:25:07Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

+            return false;
+        }
+
+        String bitsPerPixel = asset.getMetadataValue("dam:Bitsperpixel");


Ideally dam:Bitsperpixel would be a constant in https://developer.adobe.com/experience-manager/reference-materials/6-5/javadoc/com/day/cq/dam/api/DamConstants.html 🤷‍♂️

@actinium15 , is this property reliable for this use-case?

@vladbailescu, this property is inferred during asset processing by AEM (cloud services or otherwise) - while this would be a good enough heuristic, there's neither any guarantee of presence nor correctness of this property when it comes to detecting transparency.

I'd propose to not hard code this value in the code, but rather accept it as a config [0] so that customers can leverage project level code to add (more definitive) attributes signifying presence of an alpha channel.

———
[0] eg, a list of customer controlled asset-metadata-attributes (specified in a preference order)

@vladbailescu Addressed! While dam:Bitsperpixel doesn't exist in DamConstants, I've:

Added DAM_BITS_PER_PIXEL = "dam:Bitsperpixel" as a constant in the Image interface

Added a comment explaining that this should ideally be in DamConstants

Used the constant throughout the code instead of the hardcoded string

This provides the benefits of a constant while acknowledging the architectural limitation. We could propose adding this to DamConstants in a future AEM release.

@actinium15 Thanks for the feedback on the reliability concerns with dam:Bitsperpixel! You're right that a configurable approach would be more robust and customer-friendly.

Do you think it makes more sense to handle this via design policy, or would another approach be more practical?

vladbailescu · 2025-09-01T06:26:06Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

+            int bits = Integer.parseInt(bitsPerPixel);
+            return bits == 32; // 32 bits indicates PNG with alpha channel
+        } catch (NumberFormatException e) {
+            LOGGER.debug("Could not parse bits per pixel value: {}", bitsPerPixel);


Any reason for not logging this as an error?

@vladbailescu Improved! I've enhanced the logging approach:

Added debug-level logging for missing dam:Bitsperpixel metadata with message: "No bits per pixel metadata found for PNG asset"

Kept debug-level for parsing errors to avoid log noise in production

Reasoning: Missing metadata isn't an error condition - it just means we can't optimize for transparency, which is acceptable fallback behavior

This provides visibility for troubleshooting while avoiding unnecessary error-level entries for expected conditions.

vladbailescu · 2025-09-01T06:28:40Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

+    /**
+     * Auto-preserve PNG transparency configuration property.
+     */
+    private static final String PN_DESIGN_AUTO_PRESERVE_PNG_TRANSPARENCY = "autoPreservePngTransparency";


I would move this constant to the interface, along with the rest of the properties, since they become part of the API.

@vladbailescu Moved! I've relocated all PNG transparency-related constants to the Image interface:

PN_DESIGN_AUTO_PRESERVE_PNG_TRANSPARENCY = "autoPreservePngTransparency"

PNG_ALPHA_FORMAT_MODIFIER = "fmt=png-alpha"

DAM_BITS_PER_PIXEL = "dam:Bitsperpixel"

This makes them part of the public API that other implementations can rely on and follows the existing pattern of other image-related constants in the interface.

vladbailescu · 2025-09-01T06:29:54Z

bundles/core/src/main/java/com/adobe/cq/wcm/core/components/internal/models/v2/ImageImpl.java

        // if content policy delegate path is provided pass it to the image Uri
        String policyDelegatePath = request.getParameter(CONTENT_POLICY_DELEGATE_PATH);
        String dmImageUrl = null;
+        Asset asset = null;


Any reason for moving the variable definition here? Looks like it's not really used outside of the assetResource != null evaluation scope.

@vladbailescu Good catch! The variable scope was actually appropriate in this case since the asset variable is used in multiple places within the broader method scope. However, I've optimized the PNG transparency logic by:

Moving PNG transparency checks into the convenience method

Reducing variable scope where possible within the transparency detection logic

Keeping the asset variable at the appropriate scope since it's used for multiple purposes (UUID, metadata extraction, transparency detection)

The current scope provides the best balance between readability and proper variable lifecycle management.

codecov · 2025-09-01T14:39:39Z

Codecov Report

❌ Patch coverage is 9.09091% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../core/components/internal/models/v3/ImageImpl.java	4.34%	21 Missing and 1 partial ⚠️
.../core/components/internal/models/v2/ImageImpl.java	14.28%	17 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

...es/core/src/test/java/com/adobe/cq/wcm/core/components/internal/models/v3/ImageImplTest.java

    }
+
+    @Test
+    void testPngTransparencyFeatureConfiguration() {


@OverRide

- Add constants to Image interface (PNG_ALPHA_FORMAT_MODIFIER, DAM_BITS_PER_PIXEL) - Use StandardImageHandler.PNG1_MIMETYPE instead of hardcoded string - Eliminate code duplication between v2/v3 by making methods protected - Create shouldApplyPngAlphaModifier() convenience method - Fix test method visibility with proper @OverRide - Add debug logging for missing metadata Addresses code quality concerns while maintaining backward compatibility.

sonarqubecloud · 2025-09-04T18:40:34Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Issue Fix adobe#2958 Transparent backgrounds on PNG images lost in dy…

362a5a5

…namic media URLs

khanmaroof changed the title ~~#2958 Issue Fix for Transparent backgrounds on PNG images lost in dynamic media Urls~~ Issue Fix for Transparent backgrounds on PNG images lost in dynamic media Urls Aug 30, 2025

khanmaroof changed the title ~~Issue Fix for Transparent backgrounds on PNG images lost in dynamic media Urls~~ Issue Fix for #2958 Transparent backgrounds on PNG images lost in dynamic media Urls Aug 30, 2025

khanmaroof closed this Aug 30, 2025

khanmaroof reopened this Aug 30, 2025

khanmaroof mentioned this pull request Aug 30, 2025

Transparent backgrounds on PNG images lost in dynamic media URLs #2958

Open

vladbailescu linked an issue Sep 1, 2025 that may be closed by this pull request

Transparent backgrounds on PNG images lost in dynamic media URLs #2958

Open

vladbailescu requested changes Sep 1, 2025

View reviewed changes

vladbailescu requested a review from actinium15 September 1, 2025 06:34

Merge branch 'adobe:main' into issue/2958-png-transparency-dm

701df18

github-advanced-security bot found potential problems Sep 1, 2025

View reviewed changes

Mohammad Maroof Khan and others added 2 commits September 4, 2025 20:33

Merge branch 'main' into issue/2958-png-transparency-dm

e467bc3

Issue Fix for #2958 Transparent backgrounds on PNG images lost in dynamic media Urls #2978

Are you sure you want to change the base?

Issue Fix for #2958 Transparent backgrounds on PNG images lost in dynamic media Urls #2978

Uh oh!

Conversation

khanmaroof commented Aug 30, 2025

Conditional PNG Transparency Detection

Uh oh!

vladbailescu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Sep 1, 2025

Codecov Report

Uh oh!

Check warning

sonarqubecloud bot commented Sep 4, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants