Support for multiline text and text wrapping in Caption filter

[artyomsv]

Description

Currently, the Caption filter in Thumbnailator renders text as a single horizontal line. When providing a string containing newline characters (\n) or a string that exceeds the width of the base image, the text is either rendered on one line or cut off at the image boundaries.

I would like to request support for multiline text rendering and/or automatic text wrapping within the Caption filter.

Research Conducted

Before opening this request, I investigated the current library capabilities:

• Searched existing GitHub issues and discussions for "multiline" and "text wrap" but found no native implementation or existing roadmap for this feature.
• Experimented with passing \n characters to the Caption constructor, which resulted in the characters being ignored or rendered as a single-line string.

Proposed Behavior

• Manual Line Breaks: The Caption filter should recognize \n characters and increment the vertical position for subsequent text based on the FontMetrics of the current font.
• Automatic Wrapping (Optional but preferred): A way to specify a maximum width (perhaps as a percentage of the image width) where text will automatically wrap to a new line.

Example Use Case

This is particularly useful for generating dynamic image overlays such as:

1. Long quotes or product descriptions using non-standard .ttf fonts.
2. Address blocks where data is naturally split across multiple lines.
3. Meme-style captions or informational overlays where the text length is unpredictable.

Current Workaround

The current workaround involves manually creating a BufferedImage via standard Graphics2D and LineBreakMeasurer, then passing that image into the .watermark() method. This breaks the fluent API chain and adds significant boilerplate code.

Are there any plans to implement this in the Caption class?

[coobird]

@artyomsv, thank you for filing this detailed and actionable feature request!

I won't make any promises on how and when this request will be acted upon, but it sounds like a good feature to have!

[coobird]

A few tricky points to sort out:

Platform-dependency of new line markers

First, to denote a newline, we could say "always use \n" -- however, that has a downside that user-provided strings could use different characters depending on the platform (i.e., \n for Linux and Mac OS, while \r\n for Windows, and \r for pre-X Mac OS.) -- For things to "just work", it's likely that the new line marker needs to be normalized into \n.

Text justification

Second, when dealing with multiple lines of output, the question of text justification comes into play. There will necessarily be an implicit expectation that the text will magically be centered or not depending on how the filter is called. Sometimes, left-justification would make more sense, while others maybe a center-justification would make more sense. That seems like a bit too much for Thumbnailator to decide automatically.

Therefore, a way to control the text justification is likely necessary.

Backwards compatibility of the Caption filter

Finally, there is likely code out there that's already giving \n to the Caption filter, and that code is expecting the current behavior to be the correct behavior. Recognizing \n as a marker to do multiple lines could be seen as a regression by those use cases.

Therefore, automatically doing line breaks when \n is encountered could be problematic. Adding a new mode to the Caption filter or creating a new filter all together may be a better idea.

[artyomsv]

Hi @coobird,

Thank you for the detailed feedback on the implementation considerations. I've implemented a solution addressing all three points you raised:

Implementation Summary

1. New MultilineCaption filter - A separate class to maintain backwards compatibility with existing Caption usage.

2. Newline normalization - All variants (\n, \r\n, \r) are normalized to \n for cross-platform support.

3. TextAlignment enum - Added LEFT, CENTER, and RIGHT options for horizontal text alignment within multiline blocks.

Implementation Details

The implementation includes:

• MultilineCaption.java - The new filter
• TextAlignment.java - New enum in geometry package
• Comprehensive unit tests

I noticed the PR template mentioning that pull requests aren't currently being accepted - I only came across this after completing the implementation. No worries on my end; I'm happy to keep this in my fork. If at any point you'd like to incorporate this or use it as reference, the code is available.

Best regards,
@artyomsv

[coobird]

@artyomsv, yes, I am not accepting pull requests at this time. I'll clarify that in the README, rather than showing up as part of the pull request template.