Train a reading model

Turn scanned books in your language into text you can read in Khānesh. Our free helper script uses kraken to read the pages, and you can teach it to read your book better.

How it works

Khānesh opens PDFs that have text inside them. A scanned book is only pictures of pages, so it has to be turned into text first. This is called OCR (optical character recognition).

With AI help turned on, Khānesh can do this itself. However, general-purpose AI models are often very bad at transcribing the Perso-Arabic script, especially in minority languages.

For better results, our helper script uses kraken, a free research software that uses custom-trained machine learning algorithms with optical character recognition (OCR) models made for books or manuscripts written in Perso-Arabic scripts. Our helper script makes kraken simple to use for people who aren’t professional researchers. You type a few commands, and the steps below give each one.

The learning model is saved into a single file when you’re finished, so you can choose to share it with the community or benefit from another user’s model too. Look for one under OCR models in Khānesh’s Shared library, and share yours there.

When you’re ready, use your model to scan older and public domain manuscripts into .txt files that you can easily import into Khānesh.

Before you start

You only do this once for each book.

  1. Install Python (only the first time). Download it from python.org and run the installer. On Windows, tick Add python.exe to PATH on its first screen.

  2. Make a project folder. Make a new folder, for example Zabanestan OCR on your Desktop. Download the helper script, khanesh_tools.py, and move it into this folder. Your browser may warn that this type of file can harm your computer. That’s a typical warning for downloading any script file (including .py files) from your browser. The script is safe, and is in plain text, so you can open it in a text editor to see what it does before running if you are concerned. Choose Keep and continue with the setup. Copy your book’s PDF into the folder too, and give it a short name without spaces, like book.pdf, which makes the commands easier to type.

  3. Open a command window in the folder. On Windows, open the folder in File Explorer, click the address bar at the top, type cmd and press Enter. On a Mac, open Terminal (in Applications › Utilities), type cd and a space, drag the folder into the window, and press Enter. Type each command below into this window, then press Enter.

  4. Install kraken (only the first time). It downloads a lot, so this can take several minutes:

    pip install kraken pymupdf
    

kraken is made for Linux and macOS, and the helper script also runs it on Windows. If it gives you trouble on Windows, use it through WSL instead.

What goes where

The helper script keeps everything it makes in your project folder, in three folders it creates:

  • models: the models you download and train
  • outputs: the text from your books, as .txt files
  • training: the lines you correct, and what training needs

So in the commands below, short names like book.pdf and models/persian_best.mlmodel are all you need. To use a file kept somewhere else, give its whole location in one pair of double quotes, like "C:\Users\you\Documents\book.pdf", or drag the file into the command window to paste its location.

Read a book

  1. Choose a model. This lists the models for Arabic-script books:

    python khanesh_tools.py models
    

    Choose one marked recognition:

    • Printed Persian Base Model for books printed like Persian, including Mazandarani and other languages written in Persian script.
    • Printed Urdu Base Model for books in Nastaliq, the slanting, hanging script. Urdu is usually printed in Nastaliq.
    • Printed Arabic-Script Base Model for letters Persian doesn’t have, like Sorani’s ڕ and ۆ.
  2. Download it with the ID in the first column of the list:

    python khanesh_tools.py get 10.5281/zenodo.7051644
    

    It saves the model in your models folder and shows its name, here models/persian_best.mlmodel. If you chose another model, use the name it shows in the commands below.

  3. Try a few pages first. -p chooses the pages:

    python khanesh_tools.py ocr book.pdf --model models/persian_best.mlmodel -p 1-5
    

    Each page takes a minute or two on most computers. The text is saved in your outputs folder, as book.txt.

  4. Check the text against the pages. If most of it is right, fix the rest in a text editor, run the remaining pages, and import the .txt file into Khānesh. If the same letters keep coming out wrong, teach the model your book.

Teach the model your book

A model learns from lines you’ve corrected. A few hundred lines, often 5 to 10 pages, make a real difference.

  1. Cut pages into lines:

    python khanesh_tools.py prepare book.pdf -p 1-10 --model models/persian_best.mlmodel
    

    This makes your training folder.

  2. Correct the lines. Open correct.html, in the training folder, in your browser. The quickest way is to type this into the same window. On Windows:

    start training\correct.html
    

    On a Mac:

    open training/correct.html
    

    Each line of the page appears as a picture, with the model’s reading under it. Fix the reading wherever it’s wrong. For a line that was cut badly, like half a line or a page number, tick Leave this line out. Your work is kept in that browser, so you can stop and come back.

  3. Save. Tap Save corrections. Your browser saves corrections.json in your Downloads folder: move it into the training folder.

  4. Train your model:

    python khanesh_tools.py train training --base models/persian_best.mlmodel --name my-model
    

    Without a graphics card this can take hours, so it’s good to leave it running overnight. Your new model is saved in models/my-model, and when training finishes, it shows the command to use it.

  5. Use your model to read the rest of the book, as in Read a book. If it still makes mistakes, correct a few more pages and train again.

Optional: see what you’ve corrected

You don’t need this step either. It sums up a training folder: where its lines came from, how many you’ve corrected on each page, how many you left out, and the training runs you’ve done. It also lists what you fixed most often, which shows what the model you started from gets wrong:

python khanesh_tools.py stats training

Name several training folders to see them all together.

Optional: check how well your model reads

You don’t need this step to train or use a model. It’s for when you want a number: how many characters your model gets right, compared with the model you started from.

To measure fairly, a model has to be tested on lines it never trained on. So you set a few corrected pages aside when you train:

  1. Correct a few extra pages, at least 2 more than you would otherwise. The pages you set aside aren’t used for training.

  2. Train with --holdout, and the number of pages to set aside:

    python khanesh_tools.py train training --base models/persian_best.mlmodel --name my-model --holdout 2
    

    It picks pages spread through what you corrected, and lists them. If you train again later, the same pages stay aside, so they never end up in training. Add --holdout 0 to train on them after all.

  3. Check. When training finishes, it shows this command with your new model’s name, ready to copy:

    python khanesh_tools.py check training --model YOUR_NEW_MODEL --base models/persian_best.mlmodel
    

    Both models read the pages you set aside, and you see how many characters and words in every 100 each gets right. Most people find text comfortable to fix by hand from about 95% of characters right. If your model isn’t there yet, correct more pages and train again.

Share your model in Khānesh’s Shared library, so others reading the same kind of book can use it.

Only scan or share books you have permission to share.