Watermark functionality enhancements for #3421

[antonarhipov]

• Grid layout and random positioning of watermarks per page
• Random orientation
• Per watermark font randomization of color and size
• Text watermark per-letter randomization of font, color, size, and orientation
• Sharing
• Random mirroring of image watermarks
• Add WatermarkRandomizer utility and enhance watermark request handling with new validations and randomization features

Description of Changes

---

Checklist

General

• I have read the Contribution Guidelines
• I have read the Stirling-PDF Developer Guide (if applicable)
• I have read the How to add new languages to Stirling-PDF (if applicable)
• I have performed a self-review of my own code
• My changes generate no new warnings

Documentation

• I have updated relevant docs on Stirling-PDF's doc repo (if functionality has heavily changed)
• I have read the section Add New Translation Tags (for new translation tags only)

UI Changes (if applicable)

• Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR)

Testing (if applicable)

• I have tested my changes locally. Refer to the Testing Guide for more details.

[Copilot]

Pull Request Overview

This PR adds comprehensive watermark validation and randomization capabilities to the PDF watermarking feature. The changes introduce extensive input validation, advanced watermark customization options (random positioning, rotation ranges, per-letter variations, mirroring, etc.), and deterministic randomness for testing purposes.

Key Changes:

• Added request validation with detailed error messages for watermark parameters
• Introduced WatermarkRandomizer utility class for deterministic random watermark attributes
• Extended watermark request model with 20+ new configuration fields for advanced customization
• Enhanced HTML template with collapsible advanced options and client-side validation

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
WatermarkController.java	Added comprehensive validation logic and refactored watermark rendering to support advanced features
AddWatermarkRequest.java	Extended model with validation annotations and new fields for enhanced watermark control
WatermarkRandomizer.java	New utility class providing deterministic randomization for watermark attributes
add-watermark.html	Enhanced UI with advanced options panel and client-side validation
WatermarkValidationTest.java	New test suite validating watermark parameter constraints
WatermarkControllerIntegrationTest.java	New integration tests covering various watermark scenarios
WatermarkRandomizerTest.java	Comprehensive unit tests for randomizer utility

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The maximum value for perLetterColorCount in the HTML form is set to 12, but the validation annotation in AddWatermarkRequest.java (line 164) sets @max(value = 20). This inconsistency could cause confusion for users who set values between 12 and 20 through the API directly. Consider aligning these values or documenting the reason for the difference.

Suggested change

	<input type="number" id="perLetterColorCount" name="perLetterColorCount" class="form-control" value="4" min="1" max="12">
	<small class="form-text text-muted">Number of colors to randomly select from (1-12, default: 4)</small>
	<input type="number" id="perLetterColorCount" name="perLetterColorCount" class="form-control" value="4" min="1" max="20">
	<small class="form-text text-muted">Number of colors to randomly select from (1-20, default: 4)</small>

[Ludy87]

/prdeploy

[stirlingbot]

🚀 PR Test Deployment

Your PR has been deployed for testing!

🔗 Test URL: http://185.252.234.121:4758
Security Disabled

This deployment will be automatically cleaned up when the PR is closed.

[balazs-szucs]

Hi, I took quick look, made some suggestions.

[balazs-szucs]

Checkboxes are a bit buggy on hover. Copy the checkbox template from Convert PDF to PDF-Image checkbox on this html and use that. (it is done via custom CSS that is overriding bootstrap hence, it is not your "standard bootstrap checkbox" as basically everybody assumes)

[balazs-szucs]

You can use ExceptionUtils to throw custom Exceptions

throw ExceptionUtils.createIllegalArgumentException

Although, I have pending PR about exceptions because it is currently not very consistent across the codebase.

[balazs-szucs]

You can convert this to a pre-compiled Pattern, which is more performant because it is compiled when the class is initialized. We also have a dedicated class for regex patterns at RegexPatternUtils. In that case the comment also becomes redundant because you can name your regex pattern with something like this:

private static final Pattern COLOR_PATTERN = Pattern.compile("^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$");

// Then use:
if (!COLOR_PATTERN.matcher(customColor).matches()) {

[balazs-szucs]

So, this might be a nitpick (feel free to ignore), but is it wise to do this per-character thing? I mean, performance-wise, I am scared to think what would happen when using a larger PDF 😅

[antonarhipov]

This was in the original feature request (#3421), so I thought I'd give it a try.
I'll do some testing with large PDFs and see if I can optimize this.

[balazs-szucs]

True, thanks for taking a look. I think there's probably a clever way to quasi-optimize this with some trickery by randomly calculating certain characters and using those randomized characters as anchors for others. In that case, it would still give the "look" of being random but would be more efficient. This might also be a non-issue in case your testing reveals that even large PDFs get processed without significant CPU pressure. Anyway, in the grand scheme of things, it's not that big of a deal, so no need to lose sleep over this.

[antonarhipov]

Implemented caching using the PDF Form XObject containing all watermarks once for the first page. It then draws that cached form on each subsequent page with a single operation. I tested the algorithm with a 1000-page PDF book, with 30 watermarks per page and per-letter variations for size and rotation, and it processed the document in under 1 second (on M3 mac pro).

[balazs-szucs]

So, this doesn't actually test anything, in order to test you have to do:

The big "A"'s of testing:

1. Arrange
2. Act
3. Assert

There are no assertions in this whole class, or am I missing something? 😅

[antonarhipov]

Indeed. That's an oversight. I'll make sure to correct this.

[balazs-szucs]

Wouldn't comparing like the content stream be more reliable? 🤔

[balazs-szucs]

A few more suggestions.

[balazs-szucs]

I think this should be on by default

[balazs-szucs]

I think the default should be around ~30 or so. Not 1. It looks a bit weird. For context here are two examples with my suggestion vs default:

EDIT: This might also be better capped at a more reasonable maximum. 100 watermarks is already so much that the original content is barely visible. At 1000, I would be very surprised if any PDF would still be usable.

vs

[balazs-szucs]

We use internationalization with properties files. You'll need to add the strings on front-end to src/main/resources/messages_en_GB.properties and reference them in your Thymeleaf templates using the #{key} syntax (or just copy the structure of the other items on this PDF)

[balazs-szucs]

This does not respect margins, which means basically the custom margin (e.g., the Margin from Edges (points)) only works when the random position is on, because that takes the margin but the grid positioning does not:

Random positioning:

public float[] generateRandomPosition(
    float pageWidth, float pageHeight,
    float watermarkWidth, float watermarkHeight,
    float margin, // <- Has margin parameter
    Float boundsX, Float boundsY,
    Float boundsWidth, Float boundsHeight)

float effectiveX = (boundsX != null) ? boundsX : margin;
float effectiveY = (boundsY != null) ? boundsY : margin;

vs

Grid positioning:

public List<float[]> generateGridPositions(
    float pageWidth, float pageHeight,
    float watermarkWidth, float watermarkHeight,
    int widthSpacer, int heightSpacer,
    int count) // <- NO margin parameter

[antonarhipov]

I managed to fix this for some cases, but now I gave it a second thought, and looks like the margin parameter does not make sense to implement. There are too many edge cases where it wouldn't work: font type, font size, length of the text, rotations - in many of those cases, the watermark would shift out of the boundaries. Probably it isn't even something to optimize for - it's fine that the text partially shifts out of the visible area. While it could work for some cases, it adds a lot of complexity to the code and will be harder to maintain, so I better remove this parameter for good.

[balazs-szucs]

so I better remove this parameter for good.

Sure, no worries. I think, I do agree with you on this. Thanks for looking into this.

[balazs-szucs]

This may be problematic on edge cases because of Off-By-One Error, e.g., it might exceed page boundaries because of the +1

[antonarhipov]

Same as for margin: exceeding the page boundaries for the watermarks is actually OK.
However, I see the point here - we need to ensure that the number of rendered watermarks appearing on the page should match the number the user configured in the settings. I'll give this a deeper thought.

[balazs-szucs]

I somewhat disagree. Users tend not to care about specifics, but the bigger problem is the overhead this may create because it compounds, which in turn makes the feature somewhat unreliable. The +1 isn't that much on its own; however, in this code, it determines how many times the loop can run, which means it can compound to a large difference. What makes it even worse is that it also compounds per page, so on a large poster-size PDF or a PDF with many pages, the difference would be quite significant. (as in performance degradation)

For a specific example, a 100-page document with A4 size (595x842 pixels), watermark 40*40, and spacer 10. With the bug, maxRows equals 17 and maxCols equals 12, so the loop runs 18 * 13 = 234 watermarks per page, totaling 23,400 watermarks. Without the bug, maxRows equals 16 and maxCols equals 11, so the loop runs 17 * 12 = 204 watermarks per page, totaling 20,400 watermarks. TLDR: 3,000 extra out-of-bounds watermark operations, which is approximately 14.7% overhead. On larger documents or with smaller watermarks relative to page size, this compounding effect could easily reach 40-50% overhead imho.

But I don't particularly think this would be a blocker or something, but still you can go down a very deep rabbit hole with these Off-By-One Errors.

[balazs-szucs]

I would keep this, or generatePerLetterRotation. Having generatePerLetterRotationInRange AND generatePerLetterRotation seem to me like a bit redundant.

[balazs-szucs]

I think you can extract this to the class like:

private static final Color[] COLOR_PALETTE = {
    Color.BLACK, Color.DARK_GRAY, Color.GRAY, Color.LIGHT_GRAY,
    Color.RED, Color.BLUE, Color.GREEN, Color.ORANGE,
    Color.MAGENTA, Color.CYAN, Color.PINK, Color.YELLOW
};

and call that here and also here:

    public Color generateRandomColorFromPalette(int colorCount) {
        // Predefined palette of common colors
        Color[] fullPalette = {
            Color.BLACK,
            Color.DARK_GRAY,
            Color.GRAY,
            Color.LIGHT_GRAY,
            Color.RED,
            Color.BLUE,
            Color.GREEN,
            Color.ORANGE,
            Color.MAGENTA,
            Color.CYAN,
            Color.PINK,
            Color.YELLOW
        };