OCRTextExtraction: Modern Spanish Handwriting OCR

An end-to-end Python pipeline capable of transcribing modern handwritten Spanish text (including cursive styles, accents á, é, í, ó, ú, and ñ) from raw images, exporting structured results to .txt and .pdf.

Powered by a fine-tuned Vision-Encoder-Decoder model hosted on Hugging Face:
Model Weights:

---

Key Features

• Zero English Hallucination: standard TrOCR decoders frequently hallucinate English phrases when reading Spanish. This model is fine-tuned to adhere to modern Spanish vocabulary, syntax, and sentence structure.
• Pre-trained Weights Included: uses ifesther/trocr-spanish-handwritten hosted on Hugging Face. No training required to use this tool.
• Document Segmentation: employs morphological OpenCV filters to extract individual text lines from full notebook pages.
• Direct Export: converts raw scans into .txt and .pdf reports.

---

Installation & Setup

1. Clone the repository:

   git clone [https://github.com/estherg12/OCRTextExtraction.git](https://github.com/estherg12/OCRTextExtraction.git)
   cd OCRTextExtraction
   

2. Create and activate a virtual environment: python -m venv .venv
   • Windows: .venv\Scripts\activate
   • Linux/macOS: source .venv/bin/activate
3. Install dependencies: pip install -r requirements.txt
4. Run Transcription: transcribe an image or an entire folder of handwriting images:
   • Single image:

     python main.py --image images/test3.png

   • Batch process an entire directory:

     python main.py --folder images/
     # or using batch_process.py:
     python batch_process.py images/ --output output/

---

Contributing

Contributions are highly encouraged! Whether it's improving the segmentation algorithm, optimizing inference speed, or adding new features, please see our CONTRIBUTING.md for guidelines on how to get involved.

---

Model Checkpoint

The core engine is based on a Vision-Encoder-Decoder fine-tuned on synthetic Spanish notebook text generated across 41 handwriting fonts.

• Hugging Face Hub:
• Base Checkpoint: microsoft/trocr-base-handwritten You can load the model directly in Python with Transformers:

from transformers import TrOCRProcessor, VisionEncoderDecoderModel

processor = TrOCRProcessor.from_pretrained(
    "ifesther/trocr-spanish-handwritten"
)
model = VisionEncoderDecoderModel.from_pretrained(
    "ifesther/trocr-spanish-handwritten"
)

---

Repository Architecture

• main.py: entry point for full-page processing and document export (.txt / .pdf). From here you can change the desired photo to analyze.
• generate_synthetic_dataset.py: synthetic generator used to create diverse handwriting line crops, ending in a large dataset with 30 thousand crops to train the model.
• train_trocr.py: fine-tuning script (only needed if retraining from scratch, I recommend running it from Google Collab).
• upload_model.py: was used to upload the trained model to Hugging Face.
• local_app.py: optional interactive visual UI.
• fonts/ & training_pdf/: input source materials.
• images/: samples.
• count_lines.py & check_lines.py: calculate the heights, top and bottom pixels from each line detected in a photo. Then crops each detected text line from the original image and saves it as a PNG. They will all be used by main.py to individually predict its text and then put it toghether.

---

License

This project is licensed under the MIT License.