HandwritingConverter

Turn photos of handwritten notes into searchable text and a printable PDF.

Install · Convert notes · Contribute

I built this because writing by hand is often the fastest way for me to think, but paper notes are difficult to search, revise, and print with my portable printer. HandwritingConverter connects those two workflows without pretending that handwriting OCR is perfect.

Status: working beta. The full local conversion pipeline is implemented and covered by automated tests. Recognition quality still depends heavily on handwriting, lighting, camera angle, and the installed Tesseract language data.

What it does

• accepts one or more JPG, PNG, TIFF, or other OpenCV-readable images
• preserves the image order as PDF page order
• resizes, denoises, increases contrast, and binarizes each page
• runs local Tesseract OCR without uploading notes to a cloud service
• calculates average word confidence for each page
• writes a self-contained visual review report beside the transcription and PDF
• writes a UTF-8 text transcription and a printable multipage PDF
• supports alternate Tesseract languages and page-segmentation modes
• can save processed images for recognition troubleshooting
• reports missing inputs and missing OCR installations clearly

Demo

The example above uses Input/test.jpg and a manually reviewed transcription. The sample images in Input/ are provided for local testing, not as accuracy benchmarks.

Technology

• Python 3.11+
• OpenCV for image preparation
• Tesseract and pytesseract for OCR
• ReportLab for PDF generation
• pytest and Ruff for validation
• GitHub Actions for continuous integration

Architecture

handwriting image(s)
        |
        v
resize -> denoise -> contrast enhancement -> adaptive threshold
        |
        v
local Tesseract OCR
        |
        +----> source + OCR confidence review (HTML)
        |
        +----> UTF-8 transcription
        |
        +----> printable multipage PDF

Installation

Tesseract is a system dependency and must be installed separately.

1. Install Python 3.11 or newer.
2. Install Tesseract OCR.
3. Create and activate a virtual environment.
4. Install the project dependencies.

Windows

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

If Tesseract is not on PATH, pass its executable explicitly:

python main.py Input\test.jpg --tesseract "C:\Program Files\Tesseract-OCR\tesseract.exe"

macOS or Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Install Tesseract through your system package manager. For example, use brew install tesseract on macOS or sudo apt install tesseract-ocr on Debian/Ubuntu.

Usage

Convert a single page:

python main.py Input/test.jpg

Convert several pages in reading order:

python main.py page-1.jpg page-2.jpg page-3.jpg --output output/class-notes --title "Class notes"

This creates:

• output/class-notes.html: visual source/transcription review
• output/class-notes.txt
• output/class-notes.pdf

Open the HTML report in any browser to compare every original page with the OCR result and average word confidence. The report is self-contained, so it can be moved without breaking its images. Use --no-review-report when only text and PDF output are needed.

Save the processed images when tuning recognition:

python main.py Input/test.jpg --debug-images --psm 6

Run python main.py --help for every option. Additional OCR languages require the corresponding Tesseract language package and can be selected with --language.

Development

python -m pip install -r requirements-dev.txt
ruff check main.py tests
pytest -q

The tests isolate OCR itself so they remain deterministic, while still exercising preprocessing, confidence calculation, the self-contained review report, multipage result handling, text output, and real PDF creation.

Privacy

Images and recognized text stay on the local computer. This project does not send notes to an external OCR API.

Known limitations

• Tesseract was designed primarily for printed text; highly cursive handwriting can produce poor results.
• Page rotation and perspective correction are not automatic yet.
• Text layout is intentionally simple and does not reproduce drawings or the exact page geometry.
• The committed sample photos may not represent every camera or handwriting style.

Roadmap

• add automatic orientation and perspective correction
• compare local handwriting-focused OCR backends using the same sample set
• add a small desktop interface with page previews and editable text
• add documented before/after examples after manual accuracy review

License and authorship

Created by SimpleCaci and released under the MIT License.