pdf-tools

# PDF Tools

Tools for viewing, extracting, and editing PDF files using Python libraries (pdfplumber and PyPDF2).

## Quick Start

All scripts require dependencies:
```bash
pip3 install pdfplumber PyPDF2
```

## Core Operations

### Extract Text

Extract text from PDF (all pages or specific pages):
```bash
scripts/extract_text.py document.pdf
scripts/extract_text.py document.pdf -p 1 3 5
scripts/extract_text.py document.pdf -o output.txt
```

### Get PDF Info

View metadata and structure:
```bash
scripts/pdf_info.py document.pdf
scripts/pdf_info.py document.pdf -f json
```

### Merge PDFs

Combine multiple PDFs into one:
```bash
scripts/merge_pdfs.py file1.pdf file2.pdf file3.pdf -o merged.pdf
```

### Split PDF

Split into individual pages:
```bash
scripts/split_pdf.py document.pdf -o output_dir/
```

Split by page ranges:
```bash
scripts/split_pdf.py document.pdf -o output_dir/ -m ranges -r "1-3,5-7,10-12"
```

### Rotate Pages

Rotate all pages or specific pages:
```bash
scripts/rotate_pdf.py document.pdf -o rotated.pdf -r 90
scripts/rotate_pdf.py document.pdf -o rotated.pdf -r 180 -p 1 3 5
```

### Edit Text

Add text overlay on a page:
```bash
scripts/edit_text.py document.pdf -o edited.pdf --overlay "New Text" --page 1 --x 100 --y 700
scripts/edit_text.py document.pdf -o edited.pdf --overlay "Watermark" --page 1 --x 200 --y 400 --font-size 20
```

Replace text (limited, works best for simple cases):
```bash
scripts/edit_text.py document.pdf -o edited.pdf --replace "Old Text" "New Text"
```

**Note:** PDF text editing is complex due to the format. The overlay method is more reliable than replacement.

## Workflow Patterns

### Viewing PDF Content

1. Get basic info: `scripts/pdf_info.py file.pdf`
2. Extract text to preview: `scripts/extract_text.py file.pdf -p 1`
3. Extract full text if needed: `scripts/extract_text.py file.pdf -o content.txt`

### Reorganizing PDFs

1. Split into pages: `scripts/split_pdf.py input.pdf -o pages/`
2. Merge selected pages: `scrip...

# PDF Tools Skill

A comprehensive OpenClaw skill for viewing, extracting, editing, and manipulating PDF files using Python libraries (pdfplumber, PyPDF2, and reportlab).

## Features

- 📄 **Text Extraction** - Extract text from entire PDFs or specific pages
- ✏️ **Text Editing** - Add text overlays to PDF pages with custom positioning and font size
- 📊 **PDF Info** - View metadata, page count, dimensions, and document properties
- 🔗 **Merge PDFs** - Combine multiple PDF files into one
- ✂️ **Split PDFs** - Split by individual pages or custom page ranges
- 🔄 **Rotate Pages** - Rotate pages at 90°, 180°, 270°, or -90° angles

## Installation

### Dependencies

Install required Python packages:

```bash
pip3 install pdfplumber PyPDF2 reportlab
```

### Skill Installation

1. Download `pdf-tools-clawhub.zip`
2. Extract to your OpenClaw skills directory:
   ```bash
   unzip pdf-tools-clawhub.zip -d ~/.openclaw/workspace/skills/
   mv ~/.openclaw/workspace/skills/pdf-tools-for-clawhub ~/.openclaw/workspace/skills/pdf-tools
   ```
3. The skill will be automatically loaded by OpenClaw

## Usage

Simply ask your OpenClaw agent:

- "Extract text from this PDF"
- "Add 'CONFIDENTIAL' text to page 1"
- "Rotate pages 1-3 by 90 degrees"
- "Merge these 3 PDF files"
- "Split this PDF into separate pages"
- "Show me info about this PDF"

The agent will automatically use the appropriate script!

## Scripts Reference

### Extract Text

```bash
scripts/extract_text.py document.pdf
scripts/extract_text.py document.pdf -p 1 3 5
scripts/extract_text.py document.pdf -o output.txt
```

### Edit Text

Add text overlay:
```bash
scripts/edit_text.py input.pdf -o output.pdf --overlay "New Text" --page 1 --x 100 --y 700
scripts/edit_text.py input.pdf -o output.pdf --overlay "Watermark" --page 1 --x 200 --y 400 --font-size 20
```

Replace text (limited due to PDF format complexity):
```bash
scripts/edit_text.py input.pdf -o output.pdf --replace "Old Text" "New Text"
```

**Note:** Text overla...