PDF Unimposition
Relevant source files
The following files were used as context for generating this wiki page:
PDF Unimposition is a specialized utility within the Duplicator project designed to reverse the process of document imposition. Its primary purpose is to transform a "booklet" formatted PDF—where multiple logical pages are printed on single large sheets (e.g., A3)—back into a standard sequential PDF with individual pages (e.g., A4). This is essential for recovering original documents from already imposed files or preparing booklet content for digital reading.
The system supports two primary methods: reordering pages from a classic booklet pattern and splitting double-page spreads where the first page (cover) remains intact while subsequent pages are bisected. The module leverages Ghostscript for PDF cleaning and normalization before performing the logic-heavy task of page extraction and resequencing.
Sources: app/view/unimpose.html.php:111-120, README.md:37-37, app/models/unimpose.php:7-15
System Architecture
The Unimposition feature follows a Model-View-Controller (MVC) pattern. The view provides a drag-and-drop interface for file uploads and mode selection. The controller/model handles file validation, temporary storage, and invokes the underlying logic classes to perform the PDF transformation.
Core Components
| Component | Responsibility |
|---|---|
View (unimpose.html.php) | User interface for file selection and mode configuration. |
Action Controller (unimpose.php) | Manages HTTP POST requests, file uploads, and temporary directories. |
Logic Engine (unimpose_logic.php) | Contains the UnimposeBooklet class which calculates page coordinates and split points. |
| External Dependency (Ghostscript) | Used for PDF cleaning (-sDEVICE=pdfwrite) to ensure compatibility with FPDI. |
Sources: app/models/unimpose.php:127-140, app/view/unimpose.html.php:68-100, app/models/unimpose_logic.php
Processing Workflow
The following diagram illustrates the data flow from user upload to the generation of the unimposed PDF.
Unimposition Modes
The system provides two distinct logic paths based on the input document structure.
Classic Booklet (Livret Classique)
This mode reverses a standard booklet imposition. It reorders pages from the typical 2-up imposition pattern back into a sequential 1, 2, 3... order. It effectively converts A3 imposed pages into A4 single pages by identifying the logical page boundaries on each physical sheet.
Sources: app/view/unimpose.html.php:73-80, app/translations/en.json:549-552
Split Double Pages (Couverture + Doubles Pages)
This mode is designed for PDFs where the first page is a single cover page, followed by double-page spreads. The logic keeps the first page intact and cuts all subsequent pages in half to create individual sequential pages.
Sources: app/view/unimpose.html.php:81-87, app/models/unimpose.php:7-10
Technical Implementation
PDF Normalization
Before processing, the system forces a "cleaning" pass using Ghostscript. This ensures the PDF is normalized to Compatibility Level 1.4, which is required for reliable processing by the TcpdfFpdi (FPDI) library used in the project.
// Ghostscript command for PDF cleaning
$command = $gs_command . " -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/printer -sOutputFile=" . escapeshellarg($cleanedPdfFile) . " " . escapeshellarg($input_file) . " 2>&1";
Sources: app/models/unimpose.php:26-30, app/models/unimpose.php:84-88
The UnimposeBooklet Class
The UnimposeBooklet class in unimpose_logic.php is the primary engine. It handles:
- Page Importation: Importing pages from the cleaned source PDF.
- Coordinate Calculation: Determining the split line for double pages or the quadrants for 2-up impositions.
- Output Generation: Sequential placement of logical pages into a new PDF document.
Sequence Diagram: Processing a Request
Configuration and Parameters
The unimposition process is governed by several environment and request-time parameters.
| Parameter | Type | Description |
|---|---|---|
unimpose_mode | string | Either booklet or split_double_pages. |
pdf | file | The source PDF document (Max 50MB). |
tmpDir | string | System temporary directory used for AppImage compatibility. |
gs_command | string | Path to Ghostscript (automatically detects gswin64c.exe on Windows or gs on Linux). |
Sources: app/models/unimpose.php:20-25, app/models/unimpose.php:133-155
Conclusion
The PDF Unimposition module provides a critical reverse-engineering capability for print workflows. By combining the robustness of Ghostscript with custom reordering logic in the UnimposeBooklet class, it allows users to accurately recover sequential documents from complex booklet impositions. Its integration into the Duplicator platform ensures that users can move fluidly between print-ready imposed formats and digital-ready sequential formats.
Sources: app/translations/en.json:553-554, README.md:37-37