ovid

"And our bodies themselves are always, restlessly, changing: we shall not be, tomorrow, what we were, or what we are." — Metamorphoses

Fast, bidirectional PDF to image converter and image to PDF merger. A replacement for most pdf and image CLI libraries.

Install

Pre-built binaries (macOS & Linux):

curl -fsSL https://raw.githubusercontent.com/euceph/ovid/main/install.sh | sh

Cargo:

# Requires libjpeg-turbo >= 3.0
cargo install ovid

brew install nasm jpeg-turbo
cargo install --path .

apt install cmake nasm libclang-dev libfontconfig1-dev libjpeg-turbo8-dev pkg-config
cargo install --path .

Usage

Split - PDF to images

# All pages to PNG at 300 DPI (default)
ovid split document.pdf

# Specific pages, JPG format, custom DPI
ovid split document.pdf -f jpg -d 150 --pages 1,3-5

# Grayscale output
ovid split document.pdf --gray

# Single page to stdout (pipe to other tools)
ovid split document.pdf -o - --pages 3 > page3.png

# Smaller PNG files (~2.5x smaller, ~20% slower)
ovid split document.pdf -c small

# JPEG quality control
ovid split document.pdf -f jpg --quality 90

Merge - images to PDF

# Merge images into a PDF
ovid merge page1.png page2.png -o output.pdf

# Merge a whole directory of images
ovid merge ./scanned_pages/ -o combined.pdf

# Set page size (scales images to fit, centered)
ovid merge photos/*.jpg -o album.pdf --pagesize a4

# Page orientation (auto detects from image, or force portrait/landscape)
ovid merge photos/*.jpg -o album.pdf --pagesize a4 --orientation landscape

# Add PDF metadata
ovid merge slides/*.png -o presentation.pdf --title "My Slides" --author "Jane Doe"

# Supports PNG, JPEG, TIFF, BMP, and GIF
ovid merge scan.tiff photo.bmp diagram.gif -o mixed.pdf

# Write PDF to stdout
ovid merge *.png -o - > output.pdf

Options

-j, --threads <N>    Number of parallel threads (default: all CPUs)
-q, --quiet          Suppress progress output
-d, --dpi <DPI>      Rendering/sizing DPI, 72-2400 (default: 300)

Shell completions

# Bash
ovid completions bash > /etc/bash_completion.d/ovid

# Zsh
ovid completions zsh > ~/.zfunc/_ovid

# Fish
ovid completions fish > ~/.config/fish/completions/ovid.fish

Performance

Split (PDF to Images)

macOS — Apple M3 Pro

150-page PDF, 300 DPI:

Speedups (150pg, 300 DPI):

Scaling across document sizes (ovid only):

Linux — 2-core x86_64 VPS

150-page PDF, 300 DPI:

Speedups (150pg, 300 DPI):

Merge (Images to PDF)

50 images, 300 DPI:

Contributions

Contributions are, of course, always welcome and encouraged. Please make sure they're grounded in reality.

License

MIT