Treat maxDPI as a ceiling rather than the render resolution (#7824)

## Description of Changes

`system.maxDPI` (default **500**) is a *safety ceiling* for
user-supplied DPI — `PdfUtils.convertFromPdf`, `ScannerEffectController`
and `ConvertPdfToVideoController` all correctly reject values above it.
But six other places used it as **the working render resolution**, so
every one of them rasterises at 500 DPI on a default install.

The giveaway is that each site declares a sensible constant and then
throws it away — the fallback only applies when `ApplicationProperties`
is *absent*, which never happens in a running app:

| Call site | Intended | Actual (default) | CPU overshoot (∝ DPI²) |
|---|---|---|---|
| `BlankPageController` | 30 | 500 | **278×** |
| `FlattenController` (no `renderDpi` sent) | 100 | 500 | 25× |
| `PdfUtils.convertPdfToPdfImage` — watermark→image, redact, manual
redact | 300 | 500 | 2.8× |
| `OCRController` | 300 | 500 | 2.8× |
| `ExtractImageScansController` | 300 | 500 | 2.8× |
| `InvertFullColorStrategy` | 300 | 500 | 2.8× |

Blank-page detection is the standout: it renders at 500 DPI purely to
compute a white-pixel percentage and throw the image away.

### What changed

Each site now uses `Math.min(<its own target>, maxDPI)`, so `maxDPI`
clamps but never raises. This is the idiom `AutoRotateController` and
`FormUtils` already use. Targets are named constants rather than inline
literals.

`FlattenController`'s explicit-`renderDpi` path was already correct and
is untouched; only its no-request default changed.

### Chosen values

- **300** for everything that rasterises output a user keeps
(watermark→image, redact, flatten, invert, extract-image-scans) — the
print standard, consistent with the DPI default in #7823.
- **300** for OCR — Tesseract's own recommended minimum. More pixels
cost time without improving recognition.
- **150** for blank-page detection, *not* the author's 30. See below.

### Why blank detection is 150, not 30

I measured it rather than trusting the constant. Rendering scan-like
pages and running `isBlankImage`'s statistic (threshold 10, blank at
≥99.9% white):

```
content          30dpi     50dpi     72dpi    100dpi    150dpi    300dpi    500dpi
empty            BLANK     BLANK     BLANK     BLANK     BLANK     BLANK     BLANK
specks           BLANK     BLANK     BLANK     BLANK     BLANK     BLANK     BLANK
thin-line        BLANK     keep      BLANK     keep      keep      keep      keep
one-word         BLANK     BLANK     BLANK     BLANK     BLANK     BLANK     BLANK
paragraph        keep      keep      keep      keep      keep      keep      keep
```

**At 30 DPI a page containing a thin rule is classified blank and
deleted** — a thin line antialiases into near-white. 72 flips the same
way. 150 matches the 300/500 verdict on every case, so it preserves
today's behaviour exactly at 1/11th the pixels. Using the author's 30
would have shipped data loss.

(Unrelated but visible above: `one-word` is already classified blank at
*every* DPI including today's 500. That is a threshold weakness, not a
DPI one, and is out of scope here.)

## Verification

`PdfUtilsMoreTest.ConvertPdfToPdfImageDpi` renders a one-inch-square
page so the embedded image's pixel width *is* the effective DPI:

- `capsAtPrintQuality` — with `maxDPI=500`, asserts 300. **Confirmed it
catches the regression**: reverting the `Math.min` fails it with
`expected: 300 but was: 500`.
- `respectsLowerCeiling` — with `maxDPI=150`, asserts 150, so the
ceiling still clamps downward.

Full suites for PdfUtils, blank-page, flatten, OCR, extract-image-scans,
invert-colour, watermark and redact all pass unchanged.

## Checklist

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes

Author: Frooodle

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

@@ -47,6 +47,9 @@
 @UtilityClass
 public class PdfUtils {
 
+    // Print-quality raster for flattening a page to an image; capped by system maxDPI
+    private static final int PDF_TO_IMAGE_DPI = 300;
+
     private final RegexPatternUtils patternCache = RegexPatternUtils.getInstance();
 
     public PDRectangle textToPageSize(String size) {
@@ -370,12 +373,12 @@ public PDDocument convertPdfToPdfImage(PDDocument document) throws IOException {
                 final int pageIndex = page;
                 BufferedImage bim;
 
-                // Use global maximum DPI setting, fallback to 300 if not set
-                int renderDpi = 300; // Default fallback
+                // maxDPI is a safety ceiling for user-supplied values, not a target resolution
+                int renderDpi = PDF_TO_IMAGE_DPI;
                 ApplicationProperties properties =
                         ApplicationContextProvider.getBean(ApplicationProperties.class);
                 if (properties != null && properties.getSystem() != null) {
-                    renderDpi = properties.getSystem().getMaxDPI();
+                    renderDpi = Math.min(renderDpi, properties.getSystem().getMaxDPI());
                 }
                 final int dpi = renderDpi;
 

app/common/src/main/java/stirling/software/common/util/misc/InvertFullColorStrategy.java

@@ -30,6 +30,9 @@
 @Slf4j
 public class InvertFullColorStrategy extends ReplaceAndInvertColorStrategy {
 
+    // Print-quality raster for the inverted page; capped by system maxDPI
+    private static final int INVERT_RENDER_DPI = 300;
+
     public InvertFullColorStrategy(MultipartFile file, ReplaceAndInvert replaceAndInvert) {
         super(file, replaceAndInvert);
     }
@@ -52,12 +55,12 @@ public InputStreamResource replace() throws IOException {
                 for (int page = 0; page < document.getNumberOfPages(); page++) {
                     BufferedImage image;
 
-                    // Use global maximum DPI setting, fallback to 300 if not set
-                    int renderDpi = 300; // Default fallback
+                    // maxDPI is a safety ceiling for user-supplied values, not a target resolution
+                    int renderDpi = INVERT_RENDER_DPI;
                     ApplicationProperties properties =
                             ApplicationContextProvider.getBean(ApplicationProperties.class);
                     if (properties != null && properties.getSystem() != null) {
-                        renderDpi = properties.getSystem().getMaxDPI();
+                        renderDpi = Math.min(renderDpi, properties.getSystem().getMaxDPI());
                     }
                     final int dpi = renderDpi;
                     final int pageNum = page;

app/common/src/test/java/stirling/software/common/util/PdfUtilsMoreTest.java

@@ -153,6 +153,52 @@ void findsPhraseOnSecondPage() throws IOException {
         }
     }
 
+    @Nested
+    @DisplayName("convertPdfToPdfImage render DPI")
+    class ConvertPdfToPdfImageDpi {
+
+        /** A one-inch-square page, so the embedded image's pixel width is the render DPI. */
+        private PDDocument oneInchPage() {
+            PDDocument doc = new PDDocument();
+            doc.addPage(new PDPage(new PDRectangle(72f, 72f)));
+            return doc;
+        }
+
+        private int embeddedImageWidth(PDDocument doc) throws IOException {
+            PDResources resources = doc.getPage(0).getResources();
+            for (var name : resources.getXObjectNames()) {
+                if (resources.isImageXObject(name)) {
+                    return ((PDImageXObject) resources.getXObject(name)).getWidth();
+                }
+            }
+            throw new IllegalStateException("no image on page");
+        }
+
+        private int renderedWidthWithMaxDpi(int maxDpi) throws IOException {
+            try (PDDocument src = oneInchPage();
+                    MockedStatic<ApplicationContextProvider> ctx =
+                            Mockito.mockStatic(ApplicationContextProvider.class)) {
+                ctx.when(() -> ApplicationContextProvider.getBean(ApplicationProperties.class))
+                        .thenReturn(propsWithMaxDpi(maxDpi));
+                try (PDDocument out = PdfUtils.convertPdfToPdfImage(src)) {
+                    return embeddedImageWidth(out);
+                }
+            }
+        }
+
+        @Test
+        @DisplayName("a high maxDPI does not raise the render resolution above 300")
+        void capsAtPrintQuality() throws IOException {
+            assertThat(renderedWidthWithMaxDpi(500)).isEqualTo(300);
+        }
+
+        @Test
+        @DisplayName("a maxDPI below the target still clamps the render resolution")
+        void respectsLowerCeiling() throws IOException {
+            assertThat(renderedWidthWithMaxDpi(150)).isEqualTo(150);
+        }
+    }
+
     // ---- convertFromPdf with ApplicationProperties present ------------------
 
     @Nested

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java

@@ -50,6 +50,10 @@
 @RequiredArgsConstructor
 public class BlankPageController {
 
+    // Lowest resolution that classifies the same as 300-500 DPI. Below this a thin rule can
+    // antialias away and a page with content is dropped as blank.
+    private static final int BLANK_DETECTION_DPI = 150;
+
     private final CustomPDFDocumentFactory pdfDocumentFactory;
     private final TempFileManager tempFileManager;
 
@@ -130,12 +134,12 @@ public ResponseEntity<Resource> removeBlankPages(
                         // Render image and save as temp file
                         BufferedImage image;
 
-                        // Use global maximum DPI setting
-                        int renderDpi = 30; // Default fallback
+                        // maxDPI is a safety ceiling for user-supplied values, not a target
+                        int renderDpi = BLANK_DETECTION_DPI;
                         ApplicationProperties properties =
                                 ApplicationContextProvider.getBean(ApplicationProperties.class);
                         if (properties != null && properties.getSystem() != null) {
-                            renderDpi = properties.getSystem().getMaxDPI();
+                            renderDpi = Math.min(renderDpi, properties.getSystem().getMaxDPI());
                         }
                         final int dpi = renderDpi;
                         final int currentPageIndex = pageIndex;

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java

@@ -53,6 +53,9 @@
 @RequiredArgsConstructor
 public class ExtractImageScansController {
 
+    // Print-quality raster for the extracted scan; capped by system maxDPI
+    private static final int SCAN_RENDER_DPI = 300;
+
     private static final String REPLACEFIRST = "[.][^.]+$";
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
@@ -112,12 +115,12 @@ public ResponseEntity<Resource> extractImageScans(
                         // Render image and save as temp file
                         BufferedImage image;
 
-                        // Use global maximum DPI setting, fallback to 300 if not set
-                        int renderDpi = 300; // Default fallback
+                        // maxDPI is a safety ceiling for user-supplied values, not a target
+                        int renderDpi = SCAN_RENDER_DPI;
                         ApplicationProperties properties =
                                 ApplicationContextProvider.getBean(ApplicationProperties.class);
                         if (properties != null && properties.getSystem() != null) {
-                            renderDpi = properties.getSystem().getMaxDPI();
+                            renderDpi = Math.min(renderDpi, properties.getSystem().getMaxDPI());
                         }
                         final int dpi = renderDpi;
                         final int pageIndex = i;

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/FlattenController.java

@@ -42,6 +42,9 @@
 @RequiredArgsConstructor
 public class FlattenController {
 
+    // Default when the caller sends no renderDpi; an explicit request still wins up to maxDPI
+    private static final int FLATTEN_RENDER_DPI = 300;
+
     private final CustomPDFDocumentFactory pdfDocumentFactory;
     private final TempFileManager tempFileManager;
 
@@ -82,7 +85,6 @@ public ResponseEntity<Resource> flatten(@ModelAttribute FlattenRequest request)
                 try (PDDocument newDocument =
                         pdfDocumentFactory.createNewDocumentBasedOnOldDocument(document)) {
 
-                    int defaultRenderDpi = 100; // Default fallback
                     ApplicationProperties properties =
                             ApplicationContextProvider.getBean(ApplicationProperties.class);
                     Integer configuredMaxDpi = null;
@@ -93,10 +95,11 @@ public ResponseEntity<Resource> flatten(@ModelAttribute FlattenRequest request)
                     int maxDpi =
                             (configuredMaxDpi != null && configuredMaxDpi > 0)
                                     ? configuredMaxDpi
-                                    : defaultRenderDpi;
+                                    : FLATTEN_RENDER_DPI;
 
                     Integer requestedDpi = request.getRenderDpi();
-                    int renderDpiTemp = maxDpi;
+                    // maxDpi is a ceiling; without an explicit request use the print-quality target
+                    int renderDpiTemp = Math.min(FLATTEN_RENDER_DPI, maxDpi);
                     if (requestedDpi != null) {
                         renderDpiTemp = Math.min(requestedDpi, maxDpi);
                         renderDpiTemp = Math.max(renderDpiTemp, 72);

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java

@@ -61,6 +61,9 @@
 @RequiredArgsConstructor
 public class OCRController {
 
+    // Tesseract's recommended minimum; more pixels cost time without improving recognition
+    private static final int OCR_RENDER_DPI = 300;
+
     private final ApplicationProperties applicationProperties;
     private final CustomPDFDocumentFactory pdfDocumentFactory;
     private final TempFileManager tempFileManager;
@@ -392,11 +395,14 @@ private void processWithTesseract(
                         // Convert page to image
                         BufferedImage image;
 
-                        // Use global maximum DPI setting, fallback to 300 if not set
-                        int renderDpi = 300; // Default fallback
+                        // maxDPI is a safety ceiling for user-supplied values, not a target
+                        int renderDpi = OCR_RENDER_DPI;
                         if (applicationProperties != null
                                 && applicationProperties.getSystem() != null) {
-                            renderDpi = applicationProperties.getSystem().getMaxDPI();
+                            renderDpi =
+                                    Math.min(
+                                            renderDpi,
+                                            applicationProperties.getSystem().getMaxDPI());
                         }
                         final int dpi = renderDpi;
                         final int currentPageNum = pageNum;