PyPDFOCR - Guide to Usage

Single conversion:

pypdfocr filename.pdf

--> filename_ocr.pdf will be generated

If you have a language pack installed, then you can specify it with the -l option:

pypdfocr -l spa filename.pdf

Folder monitoring:

pypdfocr -w watch_directory

--> Every time a pdf file is added to `watch_directory` it will be OCR'ed

Automatic filing:

To automatically move the OCR'ed pdf to a directory based on a keyword, use the -f option and specify a configuration file (described below):

pypdfocr filename.pdf -f -c config.yaml

You can also do this in folder monitoring mode:

pypdfocr -w watch_directory -f -c config.yaml

Filing based on filename match:

If no keywords match the contents of the filename, you can optionally allow it to fallback to trying to find keyword matches with the PDF filename using the -n option. For example, you may have receipts always named as receipt_2013_12_2.pdf by your scanner, and you want to move this to a folder called 'receipts'. Assuming you have a keyword receipt matching to folder receipts in your configuration file as described below, you can run the following and have this filed even if the content of the pdf does not contain the text 'receipt':

pypdfocr filename.pdf -f -c config.yaml -n

target_folder: "docs/filed"
default_folder: "docs/filed/manual_sort"
original_move_folder: "docs/originals"

folders:
    finances:
        - american express
        - chase card
        - internal revenue service
    travel:
        - boarding pass
        - airlines
        - expedia
        - orbitz
    receipts:
        - receipt

Evernote upload:

pypdfocr filename.pdf -e -c config.yaml

pypdfocr -w watch_directory -e -c config.yaml

target_folder: "evernote_stack"
default_folder: "default"
original_move_folder: "docs/originals"
evernote_developer_token: "YOUR_TOKEN"

folders:
    finances:
        - american express
        - chase card
        - internal revenue service
    travel:
        - boarding pass
        - airlines
        - expedia
        - orbitz
    receipts:
        - receipt

Auto email

You can have PyPDFOCR email you everytime it converts a file and files it. You need to first specify the following lines in the configuration file and then use the -m option when invoking pypdfocr:

mail_smtp_server: "smtp.gmail.com:587"
mail_smtp_login: "virantha@gmail.com"
mail_smtp_password: "PASSWORD"
mail_from_addr: "virantha@gmail.com"
mail_to_list:
    - "virantha@gmail.com"
    - "person2@gmail.com"

Fine-tuning Tesseract/Ghostscript/others

You can specify Tesseract and Ghostscript executable locations manually, as well as the number of concurrent processes allowed during preprocessing and tesseract. Use the following in your configuration file:

tesseract:
    binary: "/usr/bin/tesseract"
    threads: 8

ghostscript:
    binary: "/usr/local/bin/gs"

preprocess:
    threads: 8

Handling disk time-outs

If you need to increase the time interval (default 3 seconds) between new document scans when pypdfocr is watching a directory, you can specify the following option in the configuration file:

watch:
    scan_interval: 6

Using pip

PyPDFOCR is available in PyPI, so you can just run:

pip install pypdfocr

Please note that some of the 3rd-party libraries required by PyPDFOCR wiill require some build tools, especially on a default Ubuntu system. If you run into any issues using pip install, you may want to install the following packages on Ubuntu and try again:

• gcc
• libjpeg-dev
• zlib-bin
• zlib1g-dev
• python-dev

For those on Windows, because it's such a pain to get all the PIL and PDF dependencies installed, I've gone ahead and made an executable called pypdfocr.exe

You still need to install Tesseract, GhostScript, etc. as detailed below in the external dependencies list.

Manual install

Clone the source directly from github (you need to have git installed):

git clone https://github.com/virantha/pypdfocr.git

Then, install the following third-party python libraries:

• Pillow (Python Imaging Library) https://pillow.readthedocs.org/en/3.1.x/
• ReportLab (PDF generation library) http://www.reportlab.com/opensource/
• Watchdog (Cross-platform fhlesystem events monitoring) https://pypi.python.org/pypi/watchdog
• PyPDF2 (Pure python pdf library)

These can all be installed via pip:

pip install Pillow
pip install reportlab
pip install watchdog
pip install pypdf2

You will also need to install the external dependencies listed below.

External Dependencies

PyPDFOCR relies on the following (free) programs being installed and in the path:

• Tesseract OCR software https://code.google.com/p/tesseract-ocr/
• GhostScript http://www.ghostscript.com/
• ImageMagick http://www.imagemagick.org/
• Poppler http://poppler.freedesktop.org/ (Windows)

Poppler is only required if you want pypdfocr to figure out the original PDF resolution automatically; just make sure you have pdfimages in your path. Note that the xpdf provided pdfimages does not work for this, because it does not support the -list option to list the table of images in a PDF file.

On Mac OS X, you can install these using homebrew:

brew install tesseract
brew install ghostscript
brew install poppler
brew install imagemagick

On Windows, please use the installers provided on their download pages.

** Important ** Tesseract version 3.02.02 or newer required (apparently 3.02.01-6 and possibly others do not work due to a hocr output format change that I'm not planning to address). On Ubuntu, you may need to compile and install it manually by following these instructions

Also note that if you want Tesseract to recognize rotated documents (upside down, or rotated 90 degrees) then you need to find your tessdata directory and do the following:

cd /usr/local/share/tessdata
cp eng.traineddata osd.traineddata

osd stands for Orientation and Script Detection, so you need to copy the .traineddata for whatever language you want to scan in as osd.traineddata. If you don't do this step, then any landscape document will produce garbage