Watermark functionality enhancements for #3421 #4758

antonarhipov · 2025-10-29T11:15:33Z

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.

- 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

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.

app/core/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java

app/core/src/main/resources/templates/security/add-watermark.html

app/core/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java

…ecurity/WatermarkController.java remove unused variable Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…ecurity/WatermarkController.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…ecurity/WatermarkController.java save handling of bound parameters Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…ecurity/WatermarkController.java safe handling of bounds Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…commit

Ludy87 · 2025-10-29T18:52:06Z

/prdeploy

stirlingbot · 2025-10-29T18:58:43Z

🚀 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.

app/core/src/main/resources/templates/security/add-watermark.html

app/core/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java

...re/src/test/java/stirling/software/SPDF/controller/api/security/WatermarkValidationTest.java

.../java/stirling/software/SPDF/controller/api/security/WatermarkControllerIntegrationTest.java

balazs-szucs

A few more suggestions.

app/core/src/main/resources/templates/security/add-watermark.html

app/common/src/main/java/stirling/software/common/util/WatermarkRandomizer.java

…atermarkController

…in WatermarkController

…enable random positioning by default

- Introduced support for translations in watermark advanced options.

- Simplified random position generation by removing `margin` and `bounds` parameters. - Updated `WatermarkRandomizer` to avoid use of obsolete constraints. - Refactored tests to validate new approach while ensuring watermarks stay within page boundaries. - Adjusted UI and localization files to remove unused margin and bounds options.

…transformations - Enhanced text watermark rendering to calculate accurate dimensions for center-point rotation. - Added precise positioning and rotation for individual characters in per-letter variations. - Updated baseline transformations to ensure proper alignment and spacing of characters and lines.

- Introduced `generateRandomPositions` with collision detection and spacing constraints in `WatermarkRandomizer`. - Updated `WatermarkController` to use new method for generating random positions. - Added extensive test coverage for collision detection scenarios in `WatermarkRandomizerTest`.

- Implemented `PDFormXObject` to cache and reuse watermarks across PDF pages. - Adjusted `WatermarkController` to create appearance streams and handle transparency within cached objects. - Improved rendering efficiency by minimizing repetitive operations for each page.

- Moved hardcoded color palette to a static constant `PALETTE`. - Updated methods to use `PALETTE` for consistency and maintainability.

stirlingbot · 2025-11-02T13:56:07Z

🚀 Translation Verification Summary

🔄 Reference Branch: `pr-branch-messages_en_GB.properties`

📃 File Check: `messages_en_GB.properties`

Test Status: ✅ Passed
Test Status: ✅ Passed
Test Status: ✅ Passed

📃 File Check: `messages_en_US.properties`

Test Status: ✅ Passed
Test Status: ✅ Passed
Test Status: ✅ Passed

✅ Overall Check Status: Success

Thanks @antonarhipov for your help in keeping the translations up to date.

reecebrowne · 2025-11-02T16:48:53Z

/prdeploy

Frooodle · 2025-11-02T16:55:31Z

@antonarhipov Is this PR ready? Just looking through the suggested comments from @balazs-szucs and its hard to see which you have addressed as they not been closed/commented on

stirlingbot · 2025-11-02T16:55:41Z

🚀 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.

antonarhipov · 2025-11-02T18:52:05Z

@Frooodle, the PR is ready. I'm in doubt about the readability of the WatermarkController logic, though. Let me know if you'd like to refactor it.

Copilot AI review requested due to automatic review settings October 29, 2025 11:15

antonarhipov requested review from ConnorYoh, DarioGii, EthanHealy01, Frooodle, Ludy87, jbrunton96 and reecebrowne as code owners October 29, 2025 11:15

dosubot bot added size:XXL This PR changes 1000+ lines ignoring generated files. enhancement New feature or request labels Oct 29, 2025

Copilot AI reviewed Oct 29, 2025

View reviewed changes

Update app/core/src/main/java/stirling/software/SPDF/controller/api/s…

9bcb677

…ecurity/WatermarkController.java remove unused variable Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

balazs-szucs added the Priority: Medium Issues or pull requests with medium priority label Oct 29, 2025

antonarhipov and others added 5 commits October 29, 2025 13:32

Update app/core/src/main/java/stirling/software/SPDF/controller/api/s…

7d0b878

…ecurity/WatermarkController.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update app/core/src/main/java/stirling/software/SPDF/controller/api/s…

56c88fb

…ecurity/WatermarkController.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update app/core/src/main/java/stirling/software/SPDF/controller/api/s…

a506fe4

…ecurity/WatermarkController.java save handling of bound parameters Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update app/core/src/main/java/stirling/software/SPDF/controller/api/s…

a5efaf3

…ecurity/WatermarkController.java safe handling of bounds Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix the renderTextWithPerLetterVariations invocation after Copilot's …

72022c4

…commit

Ludy87 linked an issue Oct 29, 2025 that may be closed by this pull request

[Feature Request]: Extended option for Watermark fonction #3421

Open

1 task

stirlingbot bot added the pr-deployed Pull request has been deployed to a test environment label Oct 29, 2025

balazs-szucs reviewed Oct 29, 2025

View reviewed changes

antonarhipov added 12 commits October 30, 2025 13:56

fix for the checkboxes highlight on hover

2fb895d

WatermarkController: use ExceptionUtils to throw custom Exceptions

371cd1d

Add RegexPatternUtils.COLOR_PATTERN for color validation and use in W…

a62166e

…atermarkController

Refactor validation logic and improve annotation-based test coverage …

ade0074

…in WatermarkController

Update watermark default settings in UI: set default count to 30 and …

d0b8673

…enable random positioning by default

Add advanced watermark options to UI

055b2ce

- Introduced support for translations in watermark advanced options.

Refactor WatermarkRandomizer to centralize color palette definition

a1a91c1

- Moved hardcoded color palette to a static constant `PALETTE`. - Updated methods to use `PALETTE` for consistency and maintainability.

remove unused generatePerLetterRotation function

41c07b2

stirlingbot bot added the Translation label Nov 2, 2025

added missing keys in messages_en_US.properties

b2d7f4e

Watermark functionality enhancements for #3421 #4758

Are you sure you want to change the base?

Watermark functionality enhancements for #3421 #4758

Uh oh!

Conversation

antonarhipov commented Oct 29, 2025

Description of Changes

Checklist

General

Documentation

UI Changes (if applicable)

Testing (if applicable)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes:

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ludy87 commented Oct 29, 2025

Uh oh!

stirlingbot bot commented Oct 29, 2025

🚀 PR Test Deployment

Uh oh!

balazs-szucs left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

balazs-szucs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stirlingbot bot commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Translation Verification Summary

🔄 Reference Branch: pr-branch-messages_en_GB.properties

📃 File Check: messages_en_GB.properties

📃 File Check: messages_en_US.properties

✅ Overall Check Status: Success

Uh oh!

reecebrowne commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Frooodle commented Nov 2, 2025

Uh oh!

stirlingbot bot commented Nov 2, 2025

🚀 PR Test Deployment

Uh oh!

antonarhipov commented Nov 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

balazs-szucs left a comment •

edited

Loading

stirlingbot bot commented Nov 2, 2025 •

edited

Loading

🔄 Reference Branch: `pr-branch-messages_en_GB.properties`

📃 File Check: `messages_en_GB.properties`

📃 File Check: `messages_en_US.properties`

reecebrowne commented Nov 2, 2025 •

edited

Loading