Resolved

Python PIL ImageFont not resizing despite font_size parameter

Python
PIL
Pillow
ImageFont
Font Rendering
Debugging
Text Processing
Bitmap Font

Text rendered at fixed ~11px size regardless of font_size setting due to silent fallback to bitmap font | Root cause was missing TrueType font files with fallback to ImageFont.load_default()

Issue

When rendering text overlays on images using customizable font sizes, the system silently defaulted to a fixed-size bitmap font (~11px) regardless of the explicitly set font_size parameter. This resulted in uniformly small text across all outputs, with no visible errors or warnings during execution. Debug output revealed a silent fallback to a bitmap font with a warning indicating that the size could not be modified.

Culprit

The issue stemmed from a silent fallback mechanism in the font-loading logic. When the specified TrueType fonts (e.g., DejaVuSans or Arial) were unavailable, the system automatically reverted to a default bitmap font without raising an error. This bitmap font ignored the font_size parameter, rendering text at a fixed, unchangeable size. The root causes included:

  1. Missing font files: The system attempted to load fonts that did not exist on the operating system, such as those in /usr/share/fonts/truetype/dejavu/ or /usr/share/fonts/TTF/arial.ttf.

  2. Silent fallback behavior: The font-loading library did not provide exceptions or warnings when the specified fonts were missing, instead silently degrading to a fixed-size bitmap font.

  3. Bitmap font limitations: The default bitmap font lacked support for dynamic resizing, overriding any specified font size.

Solution

Font Path Verification

The solution involved identifying and verifying the paths to available system fonts. By searching the system for valid TrueType font files, a suitable replacement (e.g., LiberationSans or Hack font) was identified and used as a fallback.

Updated Font Loading Logic

The font-loading process was redesigned to include a fallback chain that explicitly checks for the availability of specified fonts. If the primary font is unavailable, it attempts to load a secondary font. Only if both are unavailable does it resort to the bitmap font, with explicit warnings to the user about the fixed size limitation.

Dynamic Scaling Implementation

To ensure text scales appropriately across different screen resolutions, the font size was dynamically calculated as a percentage of the screen dimensions. This approach allowed the text to adjust proportionally to the display size, improving readability and visual consistency.

Debug Output

Additional logging was implemented to verify the loaded font and its size, ensuring transparency and facilitating troubleshooting. This included confirmation messages to indicate whether the expected font was successfully loaded or if a fallback was used.

By implementing these changes, the system now handles missing fonts gracefully, provides clear feedback to users, and ensures text is rendered at the intended size while dynamically scaling to the display resolution.