fix: preserve indexed PNG transparency to prevent black box regression when stamping PDF

[wang0331]

Root Cause

The regression came from the indexed color fast path introduced in Image.getInstance(java.awt.Image, java.awt.Color, boolean):

1. IndexColorModel images were always emitted as /Indexed images, but palette transparency (PNG tRNS / alpha table) was not propagated to PDF.
2. Transparent palette entries were therefore treated as fully opaque indexed colors, which rendered transparent signature backgrounds as black boxes.
3. Semi-transparent indexed palettes (alpha values other than 0/255) cannot be represented by simple indexed /Mask alone and require alpha mask fallback handling.

Solution

1. Added indexed transparency classification via getIndexedTransparentPaletteIndex(...):
   1. no transparency
   2. single fully transparent index (binary transparency)
   3. unsupported/complex transparency (semi-transparent or multiple transparent indices)
2. Kept the indexed fast path for fully opaque palettes.
3. For binary indexed transparency, preserved indexed output and set img.setTransparency(new int[]{index, index}) so PDF /Mask is emitted.
4. For complex indexed transparency, intentionally fall back to the existing generic RGB + SMask path, preserving alpha correctness.
5. Refactored branch structure to remove empty if and improve readability.
6. Added regression test shouldFallbackToRgbWhenIndexedColorHasTransparency in ImageTest.

Related Issue: (#1524)

Unit-Tests for the new Feature/Bugfix

Executed:

• mvn -pl openpdf-core -Dtest=org.openpdf.text.ImageTest test (JDK 21)

Result:

• org.openpdf.text.ImageTest: 12 tests, 0 failures

Compatibilities Issues

• No API changes.
• Behavior change is limited to indexed images with transparency:
  • Fully opaque indexed images remain indexed.
  • Binary transparent indexed images remain indexed with /Mask.
  • Semi-transparent indexed images now use RGB + SMask for correct rendering (may increase PDF size slightly).

Your real name

account: wang0331
name: Xue-Ren Wang

Testing details

• Verified with org.openpdf.text.ImageTest.
• Reproduced stamping flow with example code from @seime and local demo org.openpdf.Main.

stamp-demo-output.pdf

[sonarqubecloud]

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

[wang0331]

@asturio