fix: flatten transparent pictures onto white before enrichment models by bunnysayzz · Pull Request #4776 · docling-project/docling

bunnysayzz · 2026-10-12T08:07:30Z

Picture enrichment models received transparent pictures as solid black. Three paths flattened RGBA with a plain convert("RGB"), which drops the alpha channel and keeps the black stored under it. This routes all three through the existing _to_rgb() helper in docling/backend/image_backend.py (added for page images in #4511), which composites transparency onto white.

Issue resolved by this Pull Request:
Resolves #4774

Checklist:

Documentation has been updated, if necessary.
Examples have been added, if necessary.
Tests have been added, if necessary.

Review evidence:

Before: a fully transparent RGBA pixel (0,0,0,0) reached the models as (0,0,0). After: it arrives as (255,255,255). Opaque RGBA, plain RGB, and L inputs pass through unchanged. Verified with a standalone pixel-level check against _to_rgb (Pillow): transparent, semi-transparent, opaque, RGB, and L cases all behave as stated. ruff check and ruff format --check pass on all three touched files (ruff 0.15.12). Full test suite not run on this machine (no model deps); no reference test data changed.

github-actions · 2026-10-12T08:07:41Z

✅ DCO Check Passed

Thanks @bunnysayzz, all your commits are properly signed off. 🎉

mergify · 2026-10-12T08:08:35Z

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

github-actions · 2026-10-12T08:09:31Z

AI triage (advisory)

Checked commit 2fe76af6cc. The analysis read the diff only. It did not run code from this pull request.

The PR moves the transparency-flattening helper _to_rgb() from image_backend.py into a new shared module docling/utils/image_utils.py as to_rgb(), then applies it to three picture-enrichment paths (picture_description_base_model, document_picture_classifier, VLM normalize_image_to_pil) that previously passed transparent images as black to the models.

CI safety: needs maintainer care before you approve CI.

tach.toml: changes CI test selection

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#4511	merged	referenced as #4511	related: PR #4511 (merged) introduced the same white-flattening helper only for page-image frames in `image_backend.py`. This PR reuses that helper by moving it to a shared module and extends the fix to picture enrichment models, which #4511 did not touch.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

github-actions

AI first review (advisory): blocker found

This review covers the full diff at f25a0fce41. It read the code and did not run it.

The main risk is the module-boundary CI check, not the pixel logic. The three changed modules now import docling.backend from model code, and tach.toml does not declare that dependency for these modules. The human reviewer must confirm that tach check passes, or decide where the shared RGB helper belongs.

_{A maintainer makes the merge decision. This review never approves the pull request.}

codecov · 2026-10-12T11:27:07Z

Codecov Report

❌ Patch coverage is 94.11765% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../picture_classifier/document_picture_classifier.py	66.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

github-actions

AI first review (advisory): no blocker found

This review covers the changes since f25a0fce41 at 8b7ca5cdfd. It read the code and did not run it.

The incremental commit fixes the earlier Tach blocker. It moves _to_rgb into docling.models.utils, a foundation-layer module that the three affected modules already list in tach.toml. The main remaining risk is that no test checks the white flattening. Confirm that CI tach check passes on the new head. Also decide whether to keep two copies of _to_rgb.

Earlier findings

fixed (blocker): New docling.backend imports are not declared in tach.toml, so the Tach check can fail
open (suggestion): No regression test checks the white flattening

_{A maintainer makes the merge decision. This review never approves the pull request.}

chrikrah

@bunnysayzz I ran the #4774 repro and tach check on 8b7ca5c. The three sites now get white and tach is clean, so I'd merge this as it stands.

$ python docling_alpha_repro.py        # the script from #4774, Python 3.12.6, Pillow 12.3.0, docling-core 2.101.1
picture description input  (picture_description_base_model.py:106): (0, 0, 0)        # base 930bf20
picture classifier input   (document_picture_classifier.py:167):   (0, 0, 0)
chart extraction via engine (vlm/_utils.py:131):                 (0, 0, 0)
picture description input  (picture_description_base_model.py:106): (255, 255, 255)  # head 8b7ca5c
picture classifier input   (document_picture_classifier.py:167):   (255, 255, 255)
chart extraction via engine (vlm/_utils.py:131):                 (255, 255, 255)

$ uvx [email protected] check
✅ All modules validated!     # base 930bf20, head 8b7ca5c, and the one-copy variant below

non-blocking: _to_rgb now lives in two places, image_backend.py:72 and docling/models/utils/__init__.py. I tried image_backend.py importing the models.utils copy with its own deleted, and also dropped the tach.toml line this commit adds. tach passes with no new depends_on entry anywhere, and the repro still gives white at all three sites.

I'd fold that in here, since the next fix to the alpha rules would otherwise reach only one copy. @dolfim-ibm, fine by me as a follow-up too.

dolfim-ibm · 2026-10-19T13:07:06Z

Please rebase on main after #4392 is merged. #4392 by @romainsc came first and changes the same two conversion lines, for the palette tRNS warning. _to_rgb covers that case too, so after the rebase it replaces the special case from #4392.

Three changes for the update:

Keep the tests from fix(vlm): avoid PIL warning on palette P+tRNS images #4392 in tests/test_picture_description_rgb_conversion.py. They pass with _to_rgb and keep the palette path covered.
Add a pixel-level test. A fully transparent picture (RGBA and palette with tRNS) must reach the model as (255, 255, 255), for both the picture description and the picture classifier paths. A plain convert("RGB") gives (0, 0, 0) for the same input, so the test detects the original defect.
Use one _to_rgb. The helper is now a copy of _to_rgb in docling/backend/image_backend.py. Move the existing helper to a shared module under docling/utils/ and import it from image_backend.py and from the three model call sites, so tach check stays clean and only one copy exists.

Three picture-enrichment paths flattened RGBA with a plain convert("RGB"), which keeps the black stored under the alpha channel, so fully transparent pictures reached the models as solid black. Route all three through the existing _to_rgb() helper from docling/backend/image_backend.py (introduced for page images in docling-project#4511), which composites transparency onto white. Fixes docling-project#4774. Signed-off-by: bunnysayzz <[email protected]>

Signed-off-by: bunnysayzz <[email protected]>

Move the transparency-flattening helper to docling.utils.image_utils, a new foundation module, and import it from the image backend and the three enrichment call sites. This removes the duplicate copy in docling.models.utils and replaces the palette tRNS special case from docling-project#4392, which to_rgb also covers. Add pixel-level tests: a fully transparent RGBA or palette+tRNS picture must reach the picture description model, the picture classifier engine, and normalize_image_to_pil as (255, 255, 255). Signed-off-by: Michele Dolfi <[email protected]>

dolfim-ibm

lgtm

bunnysayzz mentioned this pull request Oct 12, 2026

Picture enrichment models receive transparent pictures as solid black #4774

Closed

github-actions Bot added ai:ci-safe AI triage found no CI-safety concern (advisory) bug Something isn't working vlm-pipeline labels Oct 12, 2026

github-actions Bot removed the ai:ci-safe AI triage found no CI-safety concern (advisory) label Oct 12, 2026

github-actions Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread docling/models/inference_engines/vlm/_utils.py Resolved

Comment thread docling/models/picture_description_base_model.py Resolved

github-actions Bot added the ai:review-changes AI first review suggests changes label Oct 12, 2026

github-actions Bot added ai:ci-needs-care AI triage: check CI-safety findings before you approve CI and removed ai:review-changes AI first review suggests changes labels Oct 12, 2026

github-actions Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread docling/models/utils/__init__.py Resolved

github-actions Bot added the ai:review-lgtm AI first review found no blocker or major issue (advisory) label Oct 12, 2026

chrikrah approved these changes Oct 12, 2026

View reviewed changes

This was referenced Oct 13, 2026

ci: report why Bob Shell stopped, keep valid findings, and fix triage text #4799

Merged

fix(vlm): avoid PIL warning on palette P+tRNS images #4392

Merged

bunnysayzz and others added 4 commits October 19, 2026 15:31

fix: sort _to_rgb import to satisfy ruff isort

e014db4

Signed-off-by: bunnysayzz <[email protected]>

fix: move _to_rgb into docling.models.utils to satisfy tach boundaries

cc8b8e4

Signed-off-by: bunnysayzz <[email protected]>

dolfim-ibm force-pushed the fix/enrichment-transparent-pictures-4774 branch from 8b7ca5c to 2fe76af Compare October 19, 2026 13:49

github-actions Bot added ai:ci-needs-care AI triage: check CI-safety findings before you approve CI and removed ai:ci-needs-care AI triage: check CI-safety findings before you approve CI ai:review-lgtm AI first review found no blocker or major issue (advisory) labels Oct 19, 2026

dolfim-ibm approved these changes Oct 19, 2026

View reviewed changes

dolfim-ibm merged commit 0c87ce6 into docling-project:main Oct 19, 2026
53 checks passed

Navigation Menu

Repository navigation

fix: flatten transparent pictures onto white before enrichment models - #4776

fix: flatten transparent pictures onto white before enrichment models#4776
dolfim-ibm merged 4 commits into
docling-project:mainfrom
bunnysayzz:fix/enrichment-transparent-pictures-4774

bunnysayzz commented Oct 12, 2026

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

mergify Bot commented Oct 12, 2026

🟢 Enforce conventional commit

Uh oh!

github-actions Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

chrikrah left a comment

Uh oh!

dolfim-ibm commented Oct 19, 2026

Uh oh!

dolfim-ibm left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bunnysayzz commented Oct 12, 2026

Uh oh!

github-actions Bot commented Oct 12, 2026

Uh oh!

mergify Bot commented Oct 12, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

github-actions Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI triage (advisory)

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

AI first review (advisory): blocker found

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

AI first review (advisory): no blocker found

Uh oh!

Uh oh!

chrikrah left a comment

Choose a reason for hiding this comment

Uh oh!

dolfim-ibm commented Oct 19, 2026

Uh oh!

dolfim-ibm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Oct 12, 2026 •

edited

Loading

codecov Bot commented Oct 12, 2026 •

edited

Loading