or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-pdfcropmargins

A command-line program to crop the margins of PDF files, with many options.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pdfcropmargins@2.2.x

To install, run

npx @tessl/cli install tessl/pypi-pdfcropmargins@2.2.0

index.mddocs/

pdfCropMargins

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.

Package Information

  • Package Name: pdfCropMargins
  • Language: Python
  • Installation: pip install pdfCropMargins
  • Command-line tools: pdfcropmargins or pdf-crop-margins

Core Imports

from pdfCropMargins import crop

For version information:

from pdfCropMargins import __version__

Basic Usage

Command-line Usage

# Basic crop with 10% margin retention (default)
pdfcropmargins input.pdf

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

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

# Launch GUI for interactive cropping
pdfcropmargins input.pdf -gui

Library Usage

from pdfCropMargins import crop

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

if exit_code == 0:
    print(f"Successfully cropped PDF: {output_path}")
else:
    print(f"Error: {stderr}")

Architecture

pdfCropMargins operates through several key stages:

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

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

Capabilities

Core Library Function

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

def crop(argv_list=None, *, quiet=False, string_io=False):
    """
    Crop the PDF file using command-line arguments.
    
    Parameters:
    - argv_list (list, optional): Command-line arguments list. If None, uses sys.argv
    - quiet (bool, keyword-only): If True, suppresses stdout/stderr output  
    - string_io (bool, keyword-only): If True, captures stdout/stderr as strings
    
    Returns:
    tuple: (output_doc_pathname, exit_code, stdout_str, stderr_str)
    - output_doc_pathname (str | None): Path to cropped output document, None if failed
    - exit_code (int | None): Exit code from SystemExit exceptions, None on success
    - stdout_str (str | None): Captured stdout if string_io/quiet is True, None otherwise
    - stderr_str (str | None): Captured stderr if string_io/quiet is True, None otherwise
    """

Command-line Entry Point

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

def main():
    """
    Command-line entry point with exception handling and cleanup.
    
    Calls crop() with sys.argv arguments and handles:
    - KeyboardInterrupt and EOFError exceptions  
    - SystemExit exceptions for proper exit codes
    - Unexpected exceptions with traceback logging
    - Signal handling (SIGTERM, SIGHUP, SIGABRT)
    - Temporary directory cleanup
    
    Returns: None (exits with appropriate status code)
    """

Version Information

Package version constant for programmatic version checking.

__version__: str
# Current version: "2.2.1"

Command-line Arguments

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

Basic Options

  • Input/Output: Input file, -o/--output for output filename
  • Margin Control: -p/--percentRetain for margin percentage (default 10%)
  • Page Selection: -pg/--pages for specific page ranges

Advanced Cropping

  • Uniform Sizing: -u/--uniform to crop all pages to same size
  • Same Page Size: -ssp/--setSamePageSize for custom page dimensions
  • Individual Margins: -l/-r/-t/-b for left/right/top/bottom margins
  • Threshold Control: -t/--threshold for content detection sensitivity

Processing Options

  • Backend Selection: -gf/--gsFix, -pp/--pdftoppm, -mo/--getMarginsOnly
  • GUI Mode: -gui for interactive cropping interface
  • Preview: -pf/--preview to automatically open result
  • Restore: -r/--restore to undo previous cropping

Quality & Performance

  • Resolution: -x/--resX, -y/--resY for rendering resolution
  • Rotation: -nc/--noCropping to skip crop application
  • Validation: -sv/--showValues to display calculated margins

Error Handling

The crop() function handles errors gracefully:

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

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

Examples

Advanced Cropping Scenarios

from pdfCropMargins import crop

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

# GUI-based cropping with preview
crop([
    "document.pdf", 
    "-gui",         # Launch GUI
    "-pf"           # Preview result
])

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

# Restore previously cropped document
crop([
    "previously_cropped.pdf",
    "-r"            # Restore original margins
])

Error Handling Patterns

from pdfCropMargins import crop

def safe_crop_pdf(input_path, output_path, margin_percent=10):
    """Safely crop a PDF with error handling."""
    try:
        output_file, exit_code, stdout, stderr = crop([
            input_path,
            "-o", output_path,
            "-p", str(margin_percent)
        ], quiet=True)
        
        if exit_code == 0:
            return {"success": True, "output": output_file}
        else:
            return {"success": False, "error": stderr}
            
    except Exception as e:
        return {"success": False, "error": str(e)}

# Usage
result = safe_crop_pdf("input.pdf", "output.pdf", 15)
if result["success"]:
    print(f"Cropped successfully: {result['output']}")
else:
    print(f"Cropping failed: {result['error']}")