V
≑

HTR Β· 04

Preparing a test environment for working with HTR

Published: Updated: Publisher: Vestigia Scriptorium

Introduction

Before we start creating our own Ground Truth and training the HTR model, it is advisable to prepare a separate testing environment in which we can safely experiment with digitized documents, models and individual tool settings.

It is not necessary to build a server infrastructure or acquire a powerful workstation for the first experiment. It's more important to choose an environment that matches the project's goal.

Three basic options can be distinguished from a practical point of view for working with historical manuscripts:

  1. Transkribus – the easiest way without installing our own of HTR infrastructure;
  2. eScriptorium – a local or server-based graphical environment using, among other things, the Kraken system;
  3. Kraken – a separate tool controlled primarily from the command line.

Each variant is suitable for a different way of working.

1. First determine the purpose of the test environment

Before installing any software, it is advisable to answer a few basic questions.

We only want:

  • try automatic recognition of several pages;
  • create your own Ground Truth;
  • train your own model;
  • experiment with different models;
  • process documents locally without sending them to an external service;
  • automate the processing of hundreds or thousands of images;
  • connect HTR with your own program or database environment?

If we just want to understand the principle of working with HTR, a server of our own is an unnecessary complication.

However, if we want to experiment with data formats, automation, custom models and batch processing, the local environment starts to make sense.

Option A: Transkribus - the easiest way

2. When to use Transkribus

For a beginner, Transkribus is usually the fastest route to the first experiment.

No need to install Python, database, Docker or neural network framework. The user creates an account, uploads documents and works through the web application.

Transkribus enables, for example:

  • import digitized documents;
  • automatic layout analysis;
  • creating and correcting transcriptions;
  • preparation of Ground Truth;
  • use of existing HTR models;
  • training own models;
  • evaluation of results;
  • export transcripts.

For the first introduction to HTR, it is therefore appropriate to start here.

What we need

The practical minimum consists of:

  • ordinary computer;
  • modern web browser;
  • internet connection;
  • a Transkribus account;
  • several high-quality digitized pages of a historical document.

The calculations themselves do not need to be performed on your own computer.

What is no longer suitable to install

There used to be a desktop Transkribus eXpert Client. However, it is now listed as obsolete and is not being further developed; new functions are concentrated in the web application. [1]

It therefore makes no sense to build a workflow on a desktop client for a new project.

Variant B: eScriptorium – own graphical HTR environment

3. What is eScriptorium

eScriptorium is an open environment designed for working with historical documents. It provides a web interface for image import, segmentation, transcription, annotation, model training and automatic recognition.

For the HTR itself, it primarily uses the Kraken system. [2]

The advantage of eScriptorium lies in the combination of two features:

  • user works in a graphical web interface;
  • the environment itself can be run on your own computer or server.

This is suitable, for example, where we want to have image data, Ground Truth and models under our own control.

4. Recommended environment for the first local installation

The easiest way to a local eScriptorium is currently Docker.

The official eScriptorium documentation lists Docker as the recommended installation method. [3]

For example, the following configuration is suitable for a test computer:

Operating System

  • Linux;
  • macOS;
  • Windows with WSL 2.

For technical experiments, Linux is usually the most convenient, such as the current LTS release of Ubuntu.

Basic software

We need:

  • Git;
  • Docker Engine or Docker Desktop;
  • Docker Compose v2;
  • web browser.

Docker solves an important problem here: eScriptorium is not a single program, but a set of several services. It uses a web application, a PostgreSQL database, Redis, and Celery workers, among others. Docker runs individual components in separate containers. [2]

For a beginner, this is significantly easier than installing all the dependencies separately.

5. Docker check

After installing Docker, we will first verify that it works.

In the terminal:

docker --version
docker compose version

The second command is important. The current eScriptorium documentation uses the command:

docker compose

that is, Docker Compose v2.

Older standalone program:

docker-compose

is already obsolete. [3]

We can verify the functionality of Docker for example:

docker run hello-world

If the test container starts successfully, the base environment is ready.

6. Download eScriptorium

We will download the source files using Git:

git clone https://gitlab.com/scripta/escriptorium.git
cd escriptorium

Then we create a configuration file:

cp variables.env_example variables.env

The variables.env file contains local instance settings.

Before the first run, it is advisable to modify at least:

  • SECRET_KEY;
  • admin name;
  • admin password;
  • admin email;
  • possibly domain and network settings.

Even in the test environment, it is not advisable to keep the default password if the system is reachable from another part of the network. [3]

7. Starting eScriptorium

Current container images can be downloaded with the command:

docker compose pull

Then we start the environment:

docker compose up -d

The -d parameter means that the containers will run in the background.

We will check the status:

docker compose ps

By default, the local interface is available in the browser at:

http://localhost:8080/

We log in with the administrator account set in variables.env. [3]

8. How to stop eScriptorium

We can stop the test environment:

docker compose down

The data is preserved.

Be very careful with the command:

docker compose down -v

The -v option also deletes Docker volumes, so it can delete the database and stored instance data. [3]

It is therefore safer for a beginner to use the common:

docker compose down

Variant C: Kraken - work directly with the HTR engine

9. What is Kraken

Kraken is an open-source system for automatic text recognition, focused mainly on historical documents and various types of script.

It supports, among other things:

  • page segmentation;
  • line detection;
  • text recognition;
  • training custom models;
  • PAGE XML;
  • ALTO;
  • hOCR;
  • work with pretrained models. [4]

It is especially suitable for users who want to have the individual steps of the HTR process under control or to incorporate them into their own scripts.

10. Creating a isolated Python environment

Kraken should not be installed indiscriminately into system Python.

For experimental work, it is better to create a separate virtual environment.

For example:

python3 -m venv htr-env

Activation on Linux and macOS:

source htr-env/bin/activate

Then we update the installers:

python -m pip install --upgrade pip

and install Kraken:

pip install kraken

Kraken's current documentation lists installation via pip as the standard supported path. [4]

11. Kraken installation verification

After installation:

kraken --help

If help is displayed, the basic installation is working.

Kraken also has access to a repository of existing models. Available models can be viewed for example:

kraken list

Information on a specific model can be obtained using:

kraken show IDENTIFIKATOR_MODELU

Kraken thus allows you to experiment not only with your own models, but also with existing freely available models. [4]

12. First recognition test

Before training your own model, it is advisable to verify the entire processing pipeline on one image.

The processing principle is:

image β†’ segmentation β†’ recognition β†’ text/XML

With a suitable model, you can use for example:

kraken -i strana.tif vystup.txt segment -bl ocr -m model.mlmodel

Kraken first determines the line structure and then performs recognition using the specified model. [4]

The goal of this first experiment is not to get a perfect transcript.

We only need to verify that:

  • The Kraken can be launched;
  • input image can be loaded;
  • model can be loaded;
  • segmentation will occur;
  • output text will be generated.

Only then does it make sense to tackle your own training.

13. CPU or GPU?

One of the most common questions when creating an HTR environment is whether a graphics card is required.

For the following tasks alone:

  • document viewing;
  • preparation of Ground Truth;
  • correction of transcriptions;
  • small recognition tests;

A powerful GPU is not a prerequisite.

However, when training neural models, a compatible GPU can significantly speed up the process.

eScriptorium allows the training worker to use NVIDIA GPUs via the NVIDIA Container Toolkit. The current documentation uses a device setup of the type:

KRAKEN_TRAINING_DEVICE=cuda:0

and GPU configuration in Docker Compose. [3]

For the first experiment, however, it is not advisable to start by installing CUDA and drivers if it is not certain that we will need them.

A more sensible course of action is:

run the system on CPU first β†’ create a small experiment β†’ only then configure a GPU.

This will greatly reduce the number of possible sources of installation problems.

14. Recommended structure of project directories

Regardless of the tool you choose, it's useful to have your data organized from the start.

For example:

htr-projekt/
β”‚
β”œβ”€β”€ images-original/
β”‚   └── original digitized images
β”‚
β”œβ”€β”€ images-working/
β”‚   └── working image copies
β”‚
β”œβ”€β”€ ground-truth/
β”‚   └── verified transcriptions
β”‚
β”œβ”€β”€ pagexml/
β”‚   └── PAGE XML
β”‚
β”œβ”€β”€ models/
β”‚   β”œβ”€β”€ model-001/
β”‚   β”œβ”€β”€ model-002/
β”‚   └── model-003/
β”‚
β”œβ”€β”€ test/
β”‚   └── independent test data
β”‚
β”œβ”€β”€ results/
β”‚   └── experiment results
β”‚
└── documentation/
    β”œβ”€β”€ transcription-rules.md
    └── experiment-log.md

Such division is not a technical condition of the HTR system. It is an organizational measure that will start to pay off very quickly.

It is especially important to separate:

original images,
Ground Truth,
training data,
independent test data,
individual model results.

Otherwise, it can easily happen later that we don't know if a certain page was or wasn't part of the training.

15. Do not modify the original images

It is advisable to keep the original digitized files in a separate directory and not overwrite them.

If we need to change:

  • resolution;
  • contrast;
  • color;
  • crop;
  • binarization;
  • image orientation;

we will create a working copy.

The original file should be preserved.

This is important not only for the HTR experiment, but also for the general archival reproducibility of processing.

16. PAGE XML as a suitable exchange format

For longer-term work, it is not advisable to lock the project only to the internal format of one program.

One of the prominent formats used for historical documents is PAGE XML.

It can contain, for example:

  • page dimensions;
  • text regions;
  • line coordinates;
  • baselines;
  • reading order;
  • transcription;
  • additional structural information.

Kraken supports PAGE XML, and the OCR-D ecosystem also uses PAGE XML as a major Ground Truth format. [4] [5]

For an archival project, it is therefore advisable to verify that Ground Truth and results can be exported to a standardized format independent of a specific application.

17. Keep a record of experiments

A situation arises very easily:

"Model number 7 was better than model number 6, but we don't know why anymore."

Therefore, it is advisable to keep a simple protocol right from the first experiment.

For example:

Model: statek-001
Date: 2026-09-09

Training:
45 pages
8 742 words

Validation:
5 pages
963 words

Base model:
name / identifier

Settings:
...

CER validation:
7,4 %

Note:
Problems with scribe C.
Often confuses r/n and e/c.

Next version:

Model: statek-002

Change:
+15 GT pages from scribe C

CER validation:
5,8 %

Such a plain text file can be more valuable later than the autosave logs themselves.

18. Versioning

Git is suitable for configuration files, transcription rules, scripts and documentation.

For example:

git init

However, we don't need to store thousands of large TIFF images or multi-gigabyte models in Git.

Git is particularly suitable for:

  • transcription rules;
  • scripts;
  • configuration files;
  • small XML files;
  • documentation of experiments.

It is better to archive large image data in another way.

19. Backup

Ground Truth is usually more expensive than the HTR model itself.

We can train the model again.

A manually created and checked transcription of hundreds or thousands of lines can represent tens to hundreds of hours of human work.

Therefore Ground Truth should be regularly backed up in at least two independent copies.

A practical data value hierarchy tends to be:

original digitized image β†’ Ground Truth β†’ metadata and documentation β†’ model β†’ automatically generated output

Losing a model is annoying.

Losing quality Ground Truth can mean having to redo a substantial part of the entire project.

20. Recommended testing environment for a beginner

Two phases can be recommended for the first experiment.

Phase 1 - no installation

We will use:

Transkribus + 10 to 20 pages of one document

The aim is to understand:

  • segmentation;
  • baselines;
  • transcription;
  • Ground Truth;
  • existing models;
  • CER;
  • training principle.

Only if we find out that we want to use HTR systematically, will we switch to a local environment.

Phase 2 - Local Lab

On a ordinary computer, we will prepare:

Windows + WSL 2
or
Linux

+
Git
+
Docker
+
eScriptorium
+
Kraken
+
source code editor
+
Git repository for configuration and documentation

This gives us an environment in which we can experiment both through the eScriptorium GUI and directly with Kraken.

21. Recommended first technical experiment

It is not advisable to immediately upload a 300-page archival volume after installation.

For example, five to ten pages is enough.

Procedure:

1. Copy the images to the working directory.

2. Import them into eScriptorium or Transkribus.

3. Perform segmentation.

4. Check baselines.

5. Try an existing HTR model.

6. Manually fix several pages.

7. Export Ground Truth.

8. Verify that we can reload Ground Truth.

9. If we are using Kraken, run single image recognition from the command line.

10. Record the software used, the model and the result achieved.

Only when this little loop works from start to finish will we extend the experiment to tens of pages.

22. What would I choose for my own archive project

If the goal is primarily to process historical documents, not to study server management, I'd start with Transkribus.

If it turns out that we need:

  • full control over data;
  • local processing;
  • custom automation;
  • experimenting with open models;
  • connection to custom software;

I would then build a second test environment based on:

Docker + eScriptorium + Kraken.

I would use a separate installation of Kraken mainly for experiments, automated scripts and more detailed work with models.

This will create three levels:

Transkribus
β”‚
β”‚  simplest to use
β”‚
eScriptorium
β”‚
β”‚  own environment + graphical interface
β”‚
Kraken
β”‚
β”‚  command line and direct work with HTR
β”‚
own scripts and data workflows

For teaching and archival experiments, such an arrangement is more practical than trying to create a complete custom HTR infrastructure from day one.

Notes and sources used

[1] READ-COOP. How to use Transkribus eXpert (deprecated). Transkribus documentation. The Transkribus eXpert desktop client is no longer updated and new features are routed to the web application.
https://help.transkribus.org/downloading-and-installing-transkribus-expert-deprecated

[2] Scripta. eScriptorium. Source repository and project architecture description. eScriptorium integrates tools for transcription, annotation, training and recognition of historical documents and uses Kraken.
https://gitlab.com/scripta/escriptorium

[3] Scripta. eScriptorium – Install with Docker. Current installation documentation. It recommends Docker, Docker Compose v2 and also describes GPU configuration using the NVIDIA Container Toolkit.
https://gitlab.com/scripta/escriptorium/-/wikis/docker-install

[4] KIESSLING, Benjamin. Kraken 5.3 Documentation. Documentation of installation, segmentation, recognition, models and supported output formats.
https://kraken.re/5.3.0/

[5] OCR-D. The Ground Truth Guidelines. Ground Truth and PAGE XML documentation.
https://ocr-d.de/en/gt-guidelines/trans/

[6] OCR-D. OCR-D Quick Start Guide. An example of preparing a container environment using Docker and working with historical documents.
https://ocr-d.de/en/start