0
# pdfCropMargins
1

2
A comprehensive command-line program to crop the margins of PDF files, with many options. The program automatically detects margins and can crop them while preserving document metadata, handling rotated pages, and providing both command-line and GUI interfaces for interactive cropping.
3

4
## Package Information
5

6
- **Package Name**: pdfCropMargins
7
- **Language**: Python  
8
- **Installation**: `pip install pdfCropMargins`
9
- **Command-line tools**: `pdfcropmargins` or `pdf-crop-margins`
10

11
## Core Imports
12

13
```python
14
from pdfCropMargins import crop
15
```
16

17
For version information:
18

19
```python
20
from pdfCropMargins import __version__
21
```
22

23
## Basic Usage
24

25
### Command-line Usage
26

27
```bash
28
# Basic crop with 10% margin retention (default)
29
pdfcropmargins input.pdf
30

31
# Crop with custom output filename  
32
pdfcropmargins input.pdf -o output.pdf
33

34
# Crop 20% of margins, apply to pages 1-10 only
35
pdfcropmargins input.pdf -p 20 -pg 1-10
36

37
# Launch GUI for interactive cropping
38
pdfcropmargins input.pdf -gui
39
```
40

41
### Library Usage
42

43
```python
44
from pdfCropMargins import crop
45

46
# Basic programmatic cropping
47
output_path, exit_code, stdout, stderr = crop([
48
    "input.pdf",
49
    "-o", "output.pdf", 
50
    "-p", "15"  # Crop 15% of margins
51
], quiet=True)
52

53
if exit_code == 0:
54
    print(f"Successfully cropped PDF: {output_path}")
55
else:
56
    print(f"Error: {stderr}")
57
```
58

59
## Architecture
60

61
pdfCropMargins operates through several key stages:
62

63
- **Page Analysis**: Renders PDF pages as images and analyzes pixel content to detect margins
64
- **Bounding Box Detection**: Calculates precise crop boundaries based on content detection algorithms
65
- **Crop Calculation**: Determines final crop dimensions considering user preferences (uniform sizing, percentage retention, etc.)
66
- **PDF Manipulation**: Modifies MediaBox and CropBox values in the PDF structure while preserving metadata
67
- **Backend Support**: Supports multiple rendering engines (MuPDF, pdftoppm, Ghostscript) for maximum compatibility
68

69
The program preserves document metadata, handles rotated pages correctly, and includes an "undo" capability by storing original dimensions as XML metadata.
70

71
## Capabilities
72

73
### Core Library Function
74

75
The primary programmatic interface for PDF margin cropping with comprehensive argument support and output capture.
76

77
```python { .api }
78
def crop(argv_list=None, *, quiet=False, string_io=False):
79
    """
80
    Crop the PDF file using command-line arguments.
81
    
82
    Parameters:
83
    - argv_list (list, optional): Command-line arguments list. If None, uses sys.argv
84
    - quiet (bool, keyword-only): If True, suppresses stdout/stderr output  
85
    - string_io (bool, keyword-only): If True, captures stdout/stderr as strings
86
    
87
    Returns:
88
    tuple: (output_doc_pathname, exit_code, stdout_str, stderr_str)
89
    - output_doc_pathname (str | None): Path to cropped output document, None if failed
90
    - exit_code (int | None): Exit code from SystemExit exceptions, None on success
91
    - stdout_str (str | None): Captured stdout if string_io/quiet is True, None otherwise
92
    - stderr_str (str | None): Captured stderr if string_io/quiet is True, None otherwise
93
    """
94
```
95

96
### Command-line Entry Point
97

98
Command-line interface with robust exception handling and cleanup for standalone script execution.
99

100
```python { .api }
101
def main():
102
    """
103
    Command-line entry point with exception handling and cleanup.
104
    
105
    Calls crop() with sys.argv arguments and handles:
106
    - KeyboardInterrupt and EOFError exceptions  
107
    - SystemExit exceptions for proper exit codes
108
    - Unexpected exceptions with traceback logging
109
    - Signal handling (SIGTERM, SIGHUP, SIGABRT)
110
    - Temporary directory cleanup
111
    
112
    Returns: None (exits with appropriate status code)
113
    """
114
```
115

116
### Version Information
117

118
Package version constant for programmatic version checking.
119

120
```python { .api }
121
__version__: str
122
# Current version: "2.2.1"
123
```
124

125
## Command-line Arguments
126

127
The `crop()` function accepts all standard pdfcropmargins command-line arguments through the `argv_list` parameter. Key argument categories include:
128

129
### Basic Options
130
- **Input/Output**: Input file, `-o/--output` for output filename
131
- **Margin Control**: `-p/--percentRetain` for margin percentage (default 10%)
132
- **Page Selection**: `-pg/--pages` for specific page ranges
133

134
### Advanced Cropping
135
- **Uniform Sizing**: `-u/--uniform` to crop all pages to same size  
136
- **Same Page Size**: `-ssp/--setSamePageSize` for custom page dimensions
137
- **Individual Margins**: `-l/-r/-t/-b` for left/right/top/bottom margins
138
- **Threshold Control**: `-t/--threshold` for content detection sensitivity
139

140
### Processing Options  
141
- **Backend Selection**: `-gf/--gsFix`, `-pp/--pdftoppm`, `-mo/--getMarginsOnly`
142
- **GUI Mode**: `-gui` for interactive cropping interface
143
- **Preview**: `-pf/--preview` to automatically open result
144
- **Restore**: `-r/--restore` to undo previous cropping
145

146
### Quality & Performance
147
- **Resolution**: `-x/--resX`, `-y/--resY` for rendering resolution
148
- **Rotation**: `-nc/--noCropping` to skip crop application  
149
- **Validation**: `-sv/--showValues` to display calculated margins
150

151
## Error Handling
152

153
The `crop()` function handles errors gracefully:
154

155
- **SystemExit**: Normal program termination, returns exit code in second tuple element
156
- **File Errors**: Invalid input files, permission issues, corrupted PDFs  
157
- **Processing Errors**: Backend failures, memory issues, unsupported PDF features
158
- **Argument Errors**: Invalid command-line arguments, conflicting options
159

160
When `quiet=True`, error details are captured in the `stderr_str` return value for programmatic error handling.
161

162
## Examples
163

164
### Advanced Cropping Scenarios
165

166
```python
167
from pdfCropMargins import crop
168

169
# Crop with uniform page sizing and custom margins
170
output_path, exit_code, stdout, stderr = crop([
171
    "document.pdf",
172
    "-o", "cropped.pdf",
173
    "-u",           # Uniform sizing
174
    "-p", "25",     # Retain 25% of margins  
175
    "-l", "1",      # 1cm left margin
176
    "-r", "1",      # 1cm right margin
177
    "-t", "2",      # 2cm top margin  
178
    "-b", "1"       # 1cm bottom margin
179
], quiet=True)
180

181
# GUI-based cropping with preview
182
crop([
183
    "document.pdf", 
184
    "-gui",         # Launch GUI
185
    "-pf"           # Preview result
186
])
187

188
# Crop specific pages with custom threshold
189
crop([
190
    "scanned.pdf",
191
    "-pg", "1-5,10-15",    # Pages 1-5 and 10-15
192
    "-t", "200",           # Higher threshold for noisy scans
193
    "-x", "300",           # 300 DPI rendering
194
    "-y", "300"
195
])
196

197
# Restore previously cropped document
198
crop([
199
    "previously_cropped.pdf",
200
    "-r"            # Restore original margins
201
])
202
```
203

204
### Error Handling Patterns
205

206
```python
207
from pdfCropMargins import crop
208

209
def safe_crop_pdf(input_path, output_path, margin_percent=10):
210
    """Safely crop a PDF with error handling."""
211
    try:
212
        output_file, exit_code, stdout, stderr = crop([
213
            input_path,
214
            "-o", output_path,
215
            "-p", str(margin_percent)
216
        ], quiet=True)
217
        
218
        if exit_code == 0:
219
            return {"success": True, "output": output_file}
220
        else:
221
            return {"success": False, "error": stderr}
222
            
223
    except Exception as e:
224
        return {"success": False, "error": str(e)}
225

226
# Usage
227
result = safe_crop_pdf("input.pdf", "output.pdf", 15)
228
if result["success"]:
229
    print(f"Cropped successfully: {result['output']}")
230
else:
231
    print(f"Cropping failed: {result['error']}")
232
```