README.md aktualisiert
This commit is contained in:
@@ -1,2 +1,196 @@
|
|||||||
# pdf-toolkit
|
# PDF Toolkit
|
||||||
|
|
||||||
|
A small command-line toolkit for common PDF operations, built with Python and [PyMuPDF](https://pymupdf.readthedocs.io/) (`fitz`).
|
||||||
|
|
||||||
|
The scripts can:
|
||||||
|
|
||||||
|
- extract a page range from a PDF;
|
||||||
|
- join two PDF files;
|
||||||
|
- place consecutive pages side by side while preserving links; and
|
||||||
|
- remove repeated text such as a text-based watermark.
|
||||||
|
|
||||||
|
## Project structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
PDF-Toolkit/
|
||||||
|
├── requirements.txt
|
||||||
|
└── scripts/
|
||||||
|
├── extract_pages.py
|
||||||
|
├── join_files.py
|
||||||
|
├── side_by_side.py
|
||||||
|
└── watermark_remover.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.10 or later is recommended.
|
||||||
|
- Dependencies listed in `requirements.txt`.
|
||||||
|
- PyMuPDF, imported by the scripts as `fitz`.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Clone or download the project, then create and activate a virtual environment.
|
||||||
|
|
||||||
|
### macOS and Linux
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
python -m pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows PowerShell
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
python -m venv .venv
|
||||||
|
.venv\Scripts\Activate.ps1
|
||||||
|
python -m pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Run the examples below from the project root. Quote paths that contain spaces.
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
### Extract pages
|
||||||
|
|
||||||
|
`extract_pages.py` copies an inclusive range of pages from a source PDF into a new PDF. Page numbers are one-based, so the first page is page `1`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/extract_pages.py INPUT_PDF OUTPUT_PDF START END
|
||||||
|
```
|
||||||
|
|
||||||
|
Arguments:
|
||||||
|
|
||||||
|
| Argument | Description |
|
||||||
|
|---|---|
|
||||||
|
| `INPUT_PDF` | Path to the source PDF. |
|
||||||
|
| `OUTPUT_PDF` | Path for the extracted PDF. |
|
||||||
|
| `START` | First page to extract, inclusive. |
|
||||||
|
| `END` | Last page to extract, inclusive. |
|
||||||
|
|
||||||
|
Example—extract pages 3 through 8:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/extract_pages.py documents/report.pdf output/report-pages-3-8.pdf 3 8
|
||||||
|
```
|
||||||
|
|
||||||
|
The output is saved with garbage collection, compression, and font/image deflation enabled.
|
||||||
|
|
||||||
|
### Join two PDFs
|
||||||
|
|
||||||
|
`join_files.py` appends the complete second PDF to the complete first PDF and saves the result as a third file.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/join_files.py FIRST_PDF SECOND_PDF OUTPUT_PDF
|
||||||
|
```
|
||||||
|
|
||||||
|
Arguments:
|
||||||
|
|
||||||
|
| Argument | Description |
|
||||||
|
|---|---|
|
||||||
|
| `FIRST_PDF` | PDF whose pages appear first. |
|
||||||
|
| `SECOND_PDF` | PDF appended after the first file. |
|
||||||
|
| `OUTPUT_PDF` | Path for the combined PDF. |
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/join_files.py documents/part-1.pdf documents/part-2.pdf output/combined.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
This tool accepts exactly two input PDFs per invocation. To combine more files, run it repeatedly using the previous output as the next first input.
|
||||||
|
|
||||||
|
### Place pages side by side
|
||||||
|
|
||||||
|
`side_by_side.py` creates a two-page-wide, or “2-up,” PDF. It places consecutive source pages next to each other:
|
||||||
|
|
||||||
|
- the first page in each pair is placed on the left;
|
||||||
|
- the second page is placed on the right; and
|
||||||
|
- an unpaired final page is placed by itself.
|
||||||
|
|
||||||
|
The script also remaps link annotations so that external URLs and internal page links continue to work in the new layout. Other link types are copied on a best-effort basis.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/side_by_side.py INPUT_PDF OUTPUT_PDF START_PAGE
|
||||||
|
```
|
||||||
|
|
||||||
|
Arguments:
|
||||||
|
|
||||||
|
| Argument | Description |
|
||||||
|
|---|---|
|
||||||
|
| `INPUT_PDF` | Path to the source PDF. |
|
||||||
|
| `OUTPUT_PDF` | Path for the side-by-side PDF. |
|
||||||
|
| `START_PAGE` | One-based source page at which processing begins. Earlier pages are omitted. |
|
||||||
|
|
||||||
|
Example—start at page 1:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/side_by_side.py documents/manual.pdf output/manual-2up.pdf 1
|
||||||
|
```
|
||||||
|
|
||||||
|
Example—skip the cover and start at page 2:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/side_by_side.py documents/manual.pdf output/manual-2up.pdf 2
|
||||||
|
```
|
||||||
|
|
||||||
|
Because the output contains only pages from `START_PAGE` onward, internal links that point to an omitted earlier page are not expected to have a valid destination. The current implementation is best suited to files whose relevant link targets are included in the processed range.
|
||||||
|
|
||||||
|
### Remove a text watermark
|
||||||
|
|
||||||
|
`watermark_remover.py` searches every page for an exact text string, adds redaction annotations over every match, applies the redactions, and saves a cleaned copy.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/watermark_remover.py INPUT_PDF OUTPUT_PDF WATERMARK_TEXT
|
||||||
|
```
|
||||||
|
|
||||||
|
Arguments:
|
||||||
|
|
||||||
|
| Argument | Description |
|
||||||
|
|---|---|
|
||||||
|
| `INPUT_PDF` | Path to the source PDF. |
|
||||||
|
| `OUTPUT_PDF` | Path for the processed PDF. |
|
||||||
|
| `WATERMARK_TEXT` | Exact text to find and redact. Quote text containing spaces. |
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/watermark_remover.py documents/sample.pdf output/sample-clean.pdf "CONFIDENTIAL"
|
||||||
|
```
|
||||||
|
|
||||||
|
The script prints the rectangle of each match and reports the output path when processing is complete. Images intersecting a redaction are preserved because redactions are applied with `PDF_REDACT_IMAGE_NONE`.
|
||||||
|
|
||||||
|
> **Important:** This tool works on searchable PDF text. It will not detect a watermark that is embedded only as an image, converted to outlines, or otherwise absent from the PDF text layer. Redaction permanently removes matched content from the generated output, so keep the original file as a backup.
|
||||||
|
|
||||||
|
## Getting command help
|
||||||
|
|
||||||
|
Each script uses `argparse`. Run a script with `--help` to see its command syntax:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/extract_pages.py --help
|
||||||
|
python scripts/join_files.py --help
|
||||||
|
python scripts/side_by_side.py --help
|
||||||
|
python scripts/watermark_remover.py --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Input files must exist and be readable.
|
||||||
|
- The destination directory must already exist.
|
||||||
|
- Existing output files may be overwritten or may cause an error depending on the platform and PyMuPDF behavior, so use a new output path when possible.
|
||||||
|
- These scripts do not currently perform explicit validation for page ranges, encrypted PDFs, damaged files, or an output path that matches an input path.
|
||||||
|
- Always verify the generated PDF before deleting or replacing the original.
|
||||||
|
|
||||||
|
## Dependency
|
||||||
|
|
||||||
|
The scripts use PyMuPDF:
|
||||||
|
|
||||||
|
```text
|
||||||
|
PyMuPDF
|
||||||
|
```
|
||||||
|
|
||||||
|
Keep the project’s `requirements.txt` as the authoritative dependency list and install it with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user