PDF Cutter

A command-line tool to split PDF pages into a grid of tiles using TypeScript and pdf-lib.

Installation

Node.js Version

This project requires Node.js 22 or higher. You can check your current version with:

node --version

Install Dependencies (for local development)

npm install
npm run build

Image Output Requirements

To use PNG or JPG output formats (--format png or --format jpg), you need to install GraphicsMagick and Ghostscript on your system:

• macOS: brew install graphicsmagick ghostscript
• Ubuntu/Debian: sudo apt-get install graphicsmagick ghostscript
• Windows: Download from GraphicsMagick website and Ghostscript website

If these dependencies are not available, the tool will provide installation instructions when you try to use image output.

Testing

The project includes comprehensive automated tests using Vitest.

Running Tests

# Run all tests
npm run test:run

# Run tests with UI
npm run test:ui

# Run tests in watch mode
npm test

Test Coverage

The test suite covers:

• CLI argument parsing and validation
• PDF processing logic (unit conversions, tile calculations)
• End-to-end functionality (actual PDF splitting with various options)
• Error handling (invalid inputs, missing files)
• Page range processing (multi-page PDFs)
• Grid customization (different row/column combinations)
• Unit conversions (mm to pt)
• File output validation (PDF integrity checks)

Usage

Development (with tsx)

npm run dev <input.pdf> [options]

Production (compiled)

npm run start <input.pdf> [options]

Or after building:

node dist/index.js <input.pdf> [options]

CLI install from npm

Global install:

npm i -g pdf-cutter
pdf-cutter --help

One-off usage with npx:

npx pdf-cutter <input.pdf> --rows 3 --cols 3 --outdir splits

Options

• <input> — Path to input PDF file (required)
• -o, --outdir <dir> — Output directory (default: "out_splits")
• --rows <n> — Number of rows per page (default: 3)
• --cols <n> — Number of columns per page (default: 3)
• --cell-w <num> — Cell width (in units specified by --units)
• --cell-h <num> — Cell height (in units specified by --units)
• --units <u> — Units for dimensions: "mm" or "pt" (default: "mm")
• --offset-x <num> — Offset from left edge (default: 0)
• --offset-y <num> — Offset from top edge (default: 0)
• --pad-x <num> — Horizontal padding between tiles (default: 0)
• --pad-y <num> — Vertical padding between tiles (default: 0)
• --page-from <n> — First page to process (1-based, default: first page)
• --page-to <n> — Last page to process (1-based, default: last page)
• --prefix <s> — Filename prefix (default: input basename)
• --format <f> — Output format: "pdf", "png", or "jpg" (default: "pdf")

Examples

Basic 3×3 split

npm run dev booklet.pdf --rows 3 --cols 3 --outdir splits

Exact tile size with offsets

npm run dev booklet.pdf --rows 3 --cols 3 \
  --cell-w 70 --cell-h 99 --units mm \
  --offset-x 5 --offset-y 10 --outdir splits_exact

With padding between tiles

npm run dev booklet.pdf --rows 3 --cols 3 \
  --pad-x 2 --pad-y 2 --units mm

Process only specific pages

# Process only pages 2-5
npm run dev booklet.pdf --rows 3 --cols 3 \
  --page-from 2 --page-to 5 --outdir splits_pages_2_5

# Process from page 3 to the end
npm run dev booklet.pdf --rows 3 --cols 3 \
  --page-from 3 --outdir splits_from_page_3

### Output as PNG images
npm run dev booklet.pdf --rows 3 --cols 3 --format png --outdir images

### Output as JPG images
npm run dev booklet.pdf --rows 2 --cols 2 --format jpg --outdir photos

Unit Conversion

• mm to pt: points = mm × 72 ÷ 25.4 ≈ mm × 2.8346456692913385
• Default units are millimeters (mm)
• PDF coordinate system uses points (pt) with origin at bottom-left

Output

Each tile is saved as a separate file with naming convention: {prefix}_page{pageNum}_r{row}_c{col}.{ext}

Where {ext} is .pdf, .png, or .jpg depending on the --format option.

For PDF output, each file has its media box set to the tile size, so each page appears exactly the size of the cropped area.

For image output (PNG/JPG), each file contains a high-quality (300 DPI) raster image of the cropped area. Note: Image output requires GraphicsMagick and Ghostscript to be installed on your system.