[datasets] fix zero-dimension synthetic image for blank glyphs (#2016)

[ousamabenyounes]

Summary

Closes #2016

Recognition training with the synthetic WordGenerator intermittently crashes in a
DataLoader worker with:

RuntimeError: Input and output sizes should be greater than 0, but got input (H: 0, W: 29) output (H: 1, W: 128)

Root cause: synthesize_text_img sizes the canvas from font.getbbox(text). For
whitespace — and for any glyph a given font renders blank (a common case when training
with many custom --font files over a large vocab) — getbbox returns a zero-height
(or zero-width) box. h = round(1.3 * text_h) then becomes 0, so the function returns
a 0-dimension image. When that image reaches the recognition Resize, F.resize/
interpolate rejects the 0-sized input and the whole run dies.

Fix: clamp each synthesized dimension to a minimum of 1 pixel (MIN_SYNTH_IMG_DIM).
A blank glyph has no ink, so any positive size yields an equivalent (background-only)
image while keeping the tensor valid. Normal text is unaffected — 1.3*text_h and
1.1*text_w are already >= 1, so the clamp is a no-op there.

Reproduces with (unmodified main)

from doctr.datasets.generator.base import synthesize_text_img
synthesize_text_img("  ")   # -> PIL image size (W=22, H=0)  ->  crashes Resize
# RuntimeError: Input and output sizes should be greater than 0, but got input (H: 0, W: 22) output (H: 1, W: 128)

Test verification (RED -> GREEN)

New regression test tests/common/test_datasets.py::test_synthesize_text_img_never_degenerate
asserts the synthesized image is always at least 1x1.

RED — on unmodified main (fix reverted, test present):

>       assert img.height >= 1
E       assert 0 >= 1
E        +  where 0 = <PIL.Image.Image image mode=RGB size=22x0 ...>.height
2 failed in 0.10s

GREEN — with the fix:

tests/common/test_datasets.py::test_synthesize_text_img_never_degenerate[  ] PASSED
tests/common/test_datasets.py::test_synthesize_text_img_never_degenerate[   ] PASSED
2 passed in 0.21s

Full local validation suite (affected areas)

• pytest tests/common/test_datasets.py — 4 passed (2 pre-existing + 2 new)
• pytest tests/pytorch/test_datasets_pt.py::test_charactergenerator ::test_wordgenerator — 2 passed
• ruff format --check, ruff check, mypy doctr/datasets/generator/base.py — clean
• No regression vs baseline (upstream main before the change: 2 passed in the same suite)

Files changed

File	Change
doctr/datasets/generator/base.py	Clamp synthesized image dimensions to MIN_SYNTH_IMG_DIM (1 px)
tests/common/test_datasets.py	Regression test for whitespace / blank-glyph inputs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.99%. Comparing base (5332574) to head (abb0afe).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2123      +/-   ##
==========================================
- Coverage   97.00%   96.99%   -0.01%     
==========================================
  Files         169      169              
  Lines        9611     9613       +2     
==========================================
+ Hits         9323     9324       +1     
- Misses        288      289       +1     

Flag	Coverage Δ
unittests	96.99% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[felixdittrich92]

Hi @ousamabenyounes 👋,

Thanks for the PR! However, this is a false positive.

1. Whitespace characters should not be included in the vocabulary
2. Instead of silently overriding the character when there is no font that can render it, we should explicitly raise an error. In this case, it’s a user error that should be fixed by providing font(s) capable of rendering all characters

Maybe a pre-check would be useful to ensure that all characters in the vocabulary can be rendered correctly by the provided font(s)?