Add Odd-Even Merge operation mode (#1445)

* Add ODD_EVEN_MERGE sort type

* Add process method to merge odd and even PDF pages

* Add test cases for Odd-Even merge method

* Add Odd-Even Merge mode in PDF Organizer webpage

This also add a new translatable text message variable pdfOrganiser.mode.10 with translation for english and german

* Add ODD_EVEN_MERGE documentation to RearrangePagesRequest

* Add english translation for pdfOrganiser.mode.10

---------

Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>

src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java

@@ -145,6 +145,28 @@ public class RearrangePagesPDFController {
         return newPageOrder;
     }
 
+    /**
+     * Rearrange pages in a PDF file by merging odd and even pages. The first half of the pages will
+     * be the odd pages, and the second half will be the even pages as input. <br>
+     * This method is visible for testing purposes only.
+     *
+     * @param totalPages Total number of pages in the PDF file.
+     * @return List of page numbers in the new order. The first page is 0.
+     */
+    List<Integer> oddEvenMerge(int totalPages) {
+        List<Integer> newPageOrderZeroBased = new ArrayList<>();
+        int numberOfOddPages = (totalPages + 1) / 2;
+
+        for (int oneBasedIndex = 1; oneBasedIndex < (numberOfOddPages + 1); oneBasedIndex++) {
+            newPageOrderZeroBased.add((oneBasedIndex - 1));
+            if (numberOfOddPages + oneBasedIndex <= totalPages) {
+                newPageOrderZeroBased.add((numberOfOddPages + oneBasedIndex - 1));
+            }
+        }
+
+        return newPageOrderZeroBased;
+    }
+
     private List<Integer> processSortTypes(String sortTypes, int totalPages) {
         try {
             SortTypes mode = SortTypes.valueOf(sortTypes.toUpperCase());
@@ -159,6 +181,8 @@ public class RearrangePagesPDFController {
                     return sideStitchBooklet(totalPages);
                 case ODD_EVEN_SPLIT:
                     return oddEvenSplit(totalPages);
+                case ODD_EVEN_MERGE:
+                    return oddEvenMerge(totalPages);
                 case REMOVE_FIRST:
                     return removeFirst(totalPages);
                 case REMOVE_LAST:

src/main/java/stirling/software/SPDF/model/SortTypes.java

@@ -6,6 +6,7 @@ public enum SortTypes {
     BOOKLET_SORT,
     SIDE_STITCH_BOOKLET_SORT,
     ODD_EVEN_SPLIT,
+    ODD_EVEN_MERGE,
     REMOVE_FIRST,
     REMOVE_LAST,
     REMOVE_FIRST_AND_LAST,

src/main/java/stirling/software/SPDF/model/api/general/RearrangePagesRequest.java

@@ -19,6 +19,7 @@ public class RearrangePagesRequest extends PDFWithPageNums {
                             + "DUPLEX_SORT: Sorts pages as if all fronts were scanned then all backs in reverse (1, n, 2, n-1, ...). "
                             + "BOOKLET_SORT: Arranges pages for booklet printing (last, first, second, second last, ...).\n"
                             + "ODD_EVEN_SPLIT: Splits and arranges pages into odd and even numbered pages.\n"
+                            + "ODD_EVEN_MERGE: Merges pages and organises them alternately into odd and even pages.\n"
                             + "REMOVE_FIRST: Removes the first page.\n"
                             + "REMOVE_LAST: Removes the last page.\n"
                             + "REMOVE_FIRST_AND_LAST: Removes both the first and the last pages.\n")

src/main/resources/messages_de_DE.properties

@@ -821,6 +821,7 @@ pdfOrganiser.mode.6=Ungerade-Gerade-Teilung
 pdfOrganiser.mode.7=Erste entfernen
 pdfOrganiser.mode.8=Letzte entfernen
 pdfOrganiser.mode.9=Erste und letzte entfernen
+pdfOrganiser.mode.10=Ungerade-Gerade-Zusammenführung
 pdfOrganiser.placeholder=(z.B. 1,3,2 oder 4-8,2,10-12 oder 2n-1)
 
 

src/main/resources/messages_en_GB.properties

@@ -821,6 +821,7 @@ pdfOrganiser.mode.6=Odd-Even Split
 pdfOrganiser.mode.7=Remove First
 pdfOrganiser.mode.8=Remove Last
 pdfOrganiser.mode.9=Remove First and Last
+pdfOrganiser.mode.10=Odd-Even Merge
 pdfOrganiser.placeholder=(e.g. 1,3,2 or 4-8,2,10-12 or 2n-1)
 
 

src/main/resources/messages_en_US.properties

@@ -821,6 +821,7 @@ pdfOrganiser.mode.6=Odd-Even Split
 pdfOrganiser.mode.7=Remove First
 pdfOrganiser.mode.8=Remove Last
 pdfOrganiser.mode.9=Remove First and Last
+pdfOrganiser.mode.10=Odd-Even Merge
 pdfOrganiser.placeholder=(e.g. 1,3,2 or 4-8,2,10-12 or 2n-1)
 
 

src/main/resources/templates/pdf-organizer.html

@@ -28,6 +28,7 @@
                     <option value="BOOKLET_SORT" th:text="#{pdfOrganiser.mode.4}">Booklet Sort</option>
                     <option value="SIDE_STITCH_BOOKLET_SORT" th:text="#{pdfOrganiser.mode.5}">Side Stitch Booklet Sort</option>
                     <option value="ODD_EVEN_SPLIT" th:text="#{pdfOrganiser.mode.6}">Odd-Even Split</option>
+                    <option value="ODD_EVEN_MERGE" th:text="#{pdfOrganiser.mode.10}">Odd-Even Merge</option>
                     <option value="REMOVE_FIRST" th:text="#{pdfOrganiser.mode.7}">Remove First</option>
                     <option value="REMOVE_LAST" th:text="#{pdfOrganiser.mode.8}">Remove Last</option>
                     <option value="REMOVE_FIRST_AND_LAST" th:text="#{pdfOrganiser.mode.9}">Remove First and Last</option>

src/test/java/stirling/software/SPDF/controller/api/RearrangePagesPDFControllerTest.java

@@ -0,0 +1,82 @@
+package stirling.software.SPDF.controller.api;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class RearrangePagesPDFControllerTest {
+
+    /**
+     * Tests the behavior of the oddEvenMerge method when there are no pages in the document.
+     */
+    @Test
+    void oddEvenMerge_noPages() {
+        RearrangePagesPDFController sut = new RearrangePagesPDFController();
+        int totalNumberOfPages = 0;
+
+        List<Integer> newPageOrder = sut.oddEvenMerge(totalNumberOfPages);
+
+        assertNotNull(newPageOrder, "Returning null instead of page order list");
+        assertEquals(List.of(), newPageOrder, "Page order doesn't match");
+    }
+
+    /**
+     * Tests the behavior of the oddEvenMerge method when there are odd total pages in the document.
+     */
+    @Test
+    void oddEvenMerge_oddTotalPageNumber() {
+        RearrangePagesPDFController sut = new RearrangePagesPDFController();
+        int totalNumberOfPages = 5;
+
+        List<Integer> newPageOrder = sut.oddEvenMerge(totalNumberOfPages);
+
+        assertNotNull(newPageOrder, "Returning null instead of page order list");
+        assertEquals(Arrays.asList(0,3,1,4,2), newPageOrder, "Page order doesn't match");
+    }
+
+    /**
+     * Tests the behavior of the oddEvenMerge method when there are even total pages in the document.
+     */
+    @Test
+    void oddEvenMerge_evenTotalPageNumber() {
+        RearrangePagesPDFController sut = new RearrangePagesPDFController();
+        int totalNumberOfPages = 6;
+
+        List<Integer> newPageOrder = sut.oddEvenMerge(totalNumberOfPages);
+
+        assertNotNull(newPageOrder, "Returning null instead of page order list");
+        assertEquals(Arrays.asList(0,3,1,4,2,5), newPageOrder, "Page order doesn't match");
+    }
+
+    /**
+     * Tests the behavior of the oddEvenMerge method with multiple test cases of multiple pages.
+     * @param totalNumberOfPages The total number of pages in the document.
+     * @param expectedPageOrder The expected order of the pages after rearranging.
+     */
+    @ParameterizedTest
+    @CsvSource({
+            "1, '0'",
+            "2, '0,1'",
+            "3, '0,2,1'",
+            "4, '0,2,1,3'",
+            "5, '0,3,1,4,2'",
+            "6, '0,3,1,4,2,5'",
+            "10, '0,5,1,6,2,7,3,8,4,9'",
+            "50, '0,25,1,26,2,27,3,28,4,29,5,30,6,31,7,32,8,33,9,34,10,35," +
+                    "11,36,12,37,13,38,14,39,15,40,16,41,17,42,18,43,19,44,20,45,21,46," +
+                    "22,47,23,48,24,49'"
+    })
+    void oddEvenMerge_multi_test(int totalNumberOfPages, String expectedPageOrder) {
+        RearrangePagesPDFController sut = new RearrangePagesPDFController();
+
+        List<Integer> newPageOrder = sut.oddEvenMerge(totalNumberOfPages);
+
+        assertNotNull(newPageOrder, "Returning null instead of page order list");
+        assertEquals(Arrays.stream(expectedPageOrder.split(",")).map(Integer::parseInt).toList(), newPageOrder, "Page order doesn't match");
+    }
+}