feat(cbr-to-pdf,pdf-to-cbr): add PDF to/from CBR conversion with ebook optimization option (#4581)

# Description of Changes This pull request adds support for converting CBR (Comic Book RAR) files to PDF, optimizes CBZ/CBR-to-PDF conversion for e-readers using Ghostscript, and improves file type detection and image file handling. It introduces the `CbrUtils` and `PdfToCbrUtils` utility classes, refactors CBZ conversion logic, and integrates these features into the API controller. The most important changes are grouped below. ### CBR Support and Conversion: - Added the `com.github.junrar:junrar` dependency to support RAR/CBR archive extraction in `build.gradle`. (https://github.com/junrar/junrar and https://github.com/junrar/junrar?tab=License-1-ov-file#readme for repo and license) - Introduced the new utility class `CbrUtils` for converting CBR files to PDF, including image extraction, sorting, and error handling. - Added the `PdfToCbrUtils` utility class to convert PDF files into CBR archives by rendering each page as an image and packaging them. ### CBZ/CBR Conversion Optimization: - Refactored `CbzUtils.convertCbzToPdf` to support optional Ghostscript optimization for e-reader compatibility and added a new method for this. - Added `GeneralUtils.optimizePdfWithGhostscript`, which uses Ghostscript to optimize PDFs for e-readers, and integrated error handling. ### API Controller Integration: - Updated `ConvertImgPDFController` to support CBR conversion, CBZ/CBR optimization toggling, and Ghostscript availability checks. ### Endpoints <img width="1298" height="522" alt="image" src="https://github.com/user-attachments/assets/144d3e03-a637-451a-9c35-f784b2a66dc1" /> <img width="1279" height="472" alt="image" src="https://github.com/user-attachments/assets/879f221d-b775-4224-8edb-a23dbea6a0ca" /> ### UI <img width="384" height="105" alt="image" src="https://github.com/user-attachments/assets/5f861943-0706-4fad-8775-c40a9c1f3170" /> ### File Type and Image Detection Improvements: - Improved file extension detection for comic book files and image files in `CbzUtils` and added a shared regex pattern utility for image files. ### Additional notes: - Please keep in mind new the dependency, this is not dependency-free implementation (as opposed to CBZ converter) - RAR 5 currently not supported. (because JUNRAR does not support it) - Added the new ebook optimization func to GeneralUtils since we'll soon (hopefully) at least 3 book/ebook formats (EPUB, CBZ, CBR) all of which can use it. - Once again this has been thoroughly tested but can't share actual "real life" file due to copyright. Closes: #775  --- ## Checklist ### General - [x] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [x] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [x] I have performed a self-review of my own code - [x] My changes generate no new warnings ### Documentation - [x] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [x] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [x] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details. --------- Signed-off-by: Balázs Szücs <[email protected]>
2026-07-15 11:00:47 +02:00 · 2025-10-04 11:15:23 +01:00
parent fd95876d8f
commit ec1ac4cb2d
19 changed files with 856 additions and 18 deletions
@@ -0,0 +1,91 @@
+package stirling.software.SPDF.controller.api.converters;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockMultipartFile;
+
+import stirling.software.common.util.CbrUtils;
+
+class CbrUtilsTest {
+
+    @Test
+    void testIsCbrFile_ValidCbrFile() {
+        MockMultipartFile cbrFile =
+                new MockMultipartFile(
+                        "file",
+                        "test.cbr",
+                        "application/x-rar-compressed",
+                        "test content".getBytes());
+
+        assertTrue(CbrUtils.isCbrFile(cbrFile));
+    }
+
+    @Test
+    void testIsCbrFile_ValidRarFile() {
+        MockMultipartFile rarFile =
+                new MockMultipartFile(
+                        "file",
+                        "test.rar",
+                        "application/x-rar-compressed",
+                        "test content".getBytes());
+
+        assertTrue(CbrUtils.isCbrFile(rarFile));
+    }
+
+    @Test
+    void testIsCbrFile_InvalidFile() {
+        MockMultipartFile textFile =
+                new MockMultipartFile("file", "test.txt", "text/plain", "test content".getBytes());
+
+        assertFalse(CbrUtils.isCbrFile(textFile));
+    }
+
+    @Test
+    void testIsCbrFile_NoFilename() {
+        MockMultipartFile noNameFile =
+                new MockMultipartFile(
+                        "file", null, "application/x-rar-compressed", "test content".getBytes());
+
+        assertFalse(CbrUtils.isCbrFile(noNameFile));
+    }
+
+    @Test
+    void testIsCbrFile_PdfFile() {
+        MockMultipartFile pdfFile =
+                new MockMultipartFile(
+                        "file", "document.pdf", "application/pdf", "pdf content".getBytes());
+
+        assertFalse(CbrUtils.isCbrFile(pdfFile));
+    }
+
+    @Test
+    void testIsCbrFile_JpegFile() {
+        MockMultipartFile jpegFile =
+                new MockMultipartFile("file", "image.jpg", "image/jpeg", "jpeg content".getBytes());
+
+        assertFalse(CbrUtils.isCbrFile(jpegFile));
+    }
+
+    @Test
+    void testIsCbrFile_ZipFile() {
+        MockMultipartFile zipFile =
+                new MockMultipartFile(
+                        "file", "archive.zip", "application/zip", "zip content".getBytes());
+
+        assertFalse(CbrUtils.isCbrFile(zipFile));
+    }
+
+    @Test
+    void testIsCbrFile_MixedCaseExtension() {
+        MockMultipartFile cbrFile =
+                new MockMultipartFile(
+                        "file",
+                        "test.CBR",
+                        "application/x-rar-compressed",
+                        "test content".getBytes());
+
+        assertTrue(CbrUtils.isCbrFile(cbrFile));
+    }
+}