rien333 / termpdf.py

A graphical pdf (and epub, cbz, ...) reader that works inside the kitty terminal

termpdf.py

A document viewer, written in python, that works inside kitty. Hopefully a faster, less buggy, more powerful---but less portable---replacement for termpdf.

• Less portable because I have no plans of supporting graphics protocols other than the terminal graphics protocol implemented by kitty.

• Faster and more powerful because PyMuPDF offers fast image conversion and access to lots of features.

• Less buggy because it won't be a lovable but ridiculous hack of a bash script wrapped around a bunch of command line tools.

This is alpha software. Expect bugs. Expect changes. The goal is feature parity with pdf-tools.

Screenshot

Note the alpha transparency. You can toggle this on or off by pressing a.

Dependencies

• Python 3
• Kitty (unless other terminal emulators implement the same graphics protocol.)
• PyMuPDF
  • PyMuPDF in turn depends on MuPDF. On OSX, brew install mupdf-tools.

Installation

git clone https://github.com/dsanson/termpdf.py
cd termpdf.py
pip install -r requirements.txt

(You might need to use pip3 if pip is Python 2 on your system.)

Now you can run the script in place:

./termpdf.py <file.pdf>

Or copy it somewhere in your path.

Features

Document Formats

• supports the formats supported by mupdf. Tested with:
  • PDF
  • ePub
  • Html
  • CBZ
  • JPEG
• add additional format support using other tools
  • DJVU
  • CBR
  • DOCX
  • ODT
  • PPTX
  • formats from which pandoc can generate html?
• Support for encrypted documents

Commands and Interaction

• support command line arguments
  • --help
  • --version
  • --page-number
• open to last-viewed page
• vim-style ex-mode
• configuration file
• Open multiple documents at once ("buffers")
• Remote control from other apps
  • msgpack-rpc for interaction with nvim
  • SyncTeX support
  • jump to page, chapter, annotation, bookmark
  • Note-taking integration ala org-noter
• OCR
• Extract document doi/isbn
  • and add to metadata
  • and pass to external command for fetching reference data

Navigation

• vim-style navigation
  • next-page, prev-page (with counts)
  • next-chapter, prev-chapter (with counts)
  • jump to page number
  • jump to beginning, end of document
• navigate via table of contents
  • outline folding support
• navigate with bookmarks
• Thumbnail mode
  • Navigation
  • Deleting pages
  • Adding pages
  • Moving pages within document
  • Creating new document from selected pages
• Follow/fetch urls on page
• Follow urls and crossrefs on page via hints mode

Image Manipulation

• view document metadata
  • edit metadata
• page rotation
  • persistent rotation
• toggle transparency
• invert colors ("dark mode")
• toggle tinted background
• Cropping and zooming
• Reflowing (for ePub and Html)

Annotations and Editing

• Add and edit annotations
• Add and navigate with bookmarks
• Fill out forms
  • Document signing?

Text, Visual and Mouse modes

• Text mode
  • basic implementation
  • with pretty printing
  • with visual and mouse modes
• Keyboard visual mode
  • Select by word
  • Select by rectangle
  • Copy text selection
  • Copy image selection
  • Insert annotation
  • Splitting pages
• Mouse mode
  • Select by word
  • Select by rectangle
  • Copy text selection
  • Copy image selection
  • Insert annotation
  • Splitting pages