index.md

Prediction

Description

Use the teklia-dan predict command to apply a trained DAN model on an image.

Parameter	Description	Type	Default
--image-dir	Path to the folder where the images to predict are stored. Must not be provided with --image.	pathlib.Path
--image-extension	The extension of the images in the folder. Ignored if --image-dir is not provided.	str	.jpg
--model	Path to the directory containing the model, the YAML parameters file and the charset file to use for prediction.	pathlib.Path
--output	Path to the output folder. Results will be saved in this directory.	pathlib.Path
--tokens	Path to a yaml file containing a mapping between starting tokens and end tokens. Needed for entities.	pathlib.Path
--temperature	Temperature scaling scalar parameter.	float	1.0
--confidence-score	Whether to return confidence scores.	bool	False
--confidence-score-levels	Level to return confidence scores. Should be any combination of ["line", "word", "char", "ner"].	str
--attention-map	Whether to plot attention maps.	bool	False
--attention-map-scale	Image scaling factor before creating the GIF.	float	0.5
--attention-map-level	Level to plot the attention maps. Should be in ["line", "word", "char", "ner"].	str	"line"
--predict-objects	Whether to return polygons coordinates.	bool	False
--max-object-height	Maximum height for predicted objects. If set, grid search segmentation will be applied and width will be normalized to element width.	int
--word-separators	List of word separators.	list	[" ", "\n"]
--line-separators	List of line separators.	list	["\n"]
--gpu-device	Use a specific GPU if available.	int
--batch-size	Size of the batches for prediction.	int	1
--start-token	Use a specific starting token at the beginning of the prediction. Useful when making predictions on different single pages.	str
--use-language-model	Whether to use an explicit language model to rescore text hypotheses.	bool	False
--compile-model	Whether to compile the model. Recommended to speed up inference.	bool	False
--dynamic-mode	Whether to use the dynamic mode during model compilation. Recommended for prediction on images of variable size.	bool	False

The --model argument expects a directory with the following files:

• a model.pt file,
• a charset.pkl file,
• a parameters.yml file corresponding to the inference_parameters.yml file generated during training.

Examples

Predict with confidence scores

To run a prediction with confidence scores, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --confidence-score

It will create the following JSON file named after the image in the predict folder:

{
  "text": "Hansteensgt. 2 IV 28/4 - 19\nKj\u00e6re Gerhard.\nTak for Brevet om Boken og Haven\nog Crokus og Blaaveis og tak fordi\nDu vilde be mig derut sammen\nmed Kris og Ragna. Men vet Du\nda ikke, at Kris reiste med sin S\u00f8-\nster Fru Cr\u00f8ger til Lillehammer\nnogle Dage efter Begravelsen? Hen\ndes Address er Amtsingeni\u00f8r\nCr\u00f8ger. Hun skriver at de blir\nder til lidt ut i Mai. Nu er hun\nnoksaa medtat skj\u00f8nner jeg af Sorg\nog af L\u00e6ngsel, skriver saameget r\u00f8-\nrende om Oluf. Ragna har det\nherligt, skriver hun. Hun er bare\ngla, og det vet jeg, at \"Oluf er gla over,\nder hvor han nu er. Jeg har saa in-\nderlig ondt af hende, og om Du skrev\net Par Ord tror jeg det vilde gj\u00f8re\nhende godt. - Jeg gl\u00e6der mig over,\nat Du har skrevet en Bok, og\njeg er vis paa, at den er god.",
  "confidences": {
    "total": 0.99
  }
}

Predict with confidence scores and line-level attention maps

To run a prediction with confidence scores and plot line-level attention maps, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --confidence-score \
    --attention-map

It will create the following JSON file named after the image and a GIF showing a line-level attention map in the predict folder:

{
  "text": "Hansteensgt. 2 IV 28/4 - 19\nKj\u00e6re Gerhard.\nTak for Brevet om Boken og Haven\nog Crokus og Blaaveis og tak fordi\nDu vilde be mig derut sammen\nmed Kris og Ragna. Men vet Du\nda ikke, at Kris reiste med sin S\u00f8-\nster Fru Cr\u00f8ger til Lillehammer\nnogle Dage efter Begravelsen? Hen\ndes Address er Amtsingeni\u00f8r\nCr\u00f8ger. Hun skriver at de blir\nder til lidt ut i Mai. Nu er hun\nnoksaa medtat skj\u00f8nner jeg af Sorg\nog af L\u00e6ngsel, skriver saameget r\u00f8-\nrende om Oluf. Ragna har det\nherligt, skriver hun. Hun er bare\ngla, og det vet jeg, at \"Oluf er gla over,\nder hvor han nu er. Jeg har saa in-\nderlig ondt af hende, og om Du skrev\net Par Ord tror jeg det vilde gj\u00f8re\nhende godt. - Jeg gl\u00e6der mig over,\nat Du har skrevet en Bok, og\njeg er vis paa, at den er god.",
  "confidences": {
    "total": 0.99
  },
  "attention_gif": "predict/example_line.gif"
}

Predict with confidence scores and word-level attention maps

To run a prediction with confidence scores and plot word-level attention maps, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --confidence-score \
    --attention-map \
    --attention-map-level word \
    --attention-map-scale 0.5

It will create the following JSON file named after the image and a GIF showing a word-level attention map in the predict folder:

{
  "text": "Hansteensgt. 2 IV 28/4 - 19\nKj\u00e6re Gerhard.\nTak for Brevet om Boken og Haven\nog Crokus og Blaaveis og tak fordi\nDu vilde be mig derut sammen\nmed Kris og Ragna. Men vet Du\nda ikke, at Kris reiste med sin S\u00f8-\nster Fru Cr\u00f8ger til Lillehammer\nnogle Dage efter Begravelsen? Hen\ndes Address er Amtsingeni\u00f8r\nCr\u00f8ger. Hun skriver at de blir\nder til lidt ut i Mai. Nu er hun\nnoksaa medtat skj\u00f8nner jeg af Sorg\nog af L\u00e6ngsel, skriver saameget r\u00f8-\nrende om Oluf. Ragna har det\nherligt, skriver hun. Hun er bare\ngla, og det vet jeg, at \"Oluf er gla over,\nder hvor han nu er. Jeg har saa in-\nderlig ondt af hende, og om Du skrev\net Par Ord tror jeg det vilde gj\u00f8re\nhende godt. - Jeg gl\u00e6der mig over,\nat Du har skrevet en Bok, og\njeg er vis paa, at den er god.",
  "confidences": {
    "total": 0.99
  },
  "attention_gif": "predict/example_word.gif"
}

Predict with line-level attention maps and extract polygons

To run a prediction, plot line-level attention maps, and extract polygons, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --attention-map \
    --predict-objects

It will create the following JSON file named after the image and a GIF showing a line-level attention map in the predict folder:

{
  "text": "Oslo\n39 \nOresden den 24te Rasser!\nH\u00f8jst\u00e6redesherr Hartvig - assert!\nUllereder fra den f\u00f8rste tide da\njeg havder den tilfredsstillelser at vide den ar-\ndistiske ledelser af Kristiania theater i Deres\nhronder, har jeg g\u00e5t hernede med et stille\nh\u00e5b om fra Dem at modtage et forelag, sig -\nsende tils at lade \"K\u00e6rlighedens \u00abKomedie\u00bb\nopf\u00f8re fore det norske purblikum.\nEt s\u00e5dant forslag er imidlertid, imod\nforventning; ikke fremkommet, og jeg n\u00f8des der-\nfor tils self at grivbe initiativet, hvilket hervede\nsker, idet jeg\nbeder\nbet\nragte stigkket some ved denne\nskrivelse officielde indleveret til theatret. No-\nget exemplar af bogen vedlagger jeg ikke da\ndenne (i 2den udgave) med Lethed kan er -\nholdet deroppe.\nDe bet\u00e6nkeligheder, jeg i sin tid n\u00e6-\nrede mod stykkets opf\u00f8relse, er for l\u00e6nge si -\ndem forsvundne. Af manage begn er jeg kom-\nmen til den overbevisning at almenlreden\naru har f\u00e5tt sine \u00f8gne opladte for den sand -\nMed at dette arbejde i sin indersten id\u00e9 hviler\np\u00e5 et ubedinget meralsk grundlag, og brad\nstykkets hele kunstneriske struktuve ang\u00e5r,",
  "objects": [
    {
      "confidence": 0.68,
      "polygon": [
        [
          264,
          118
        ],
        [
          410,
          118
        ],
        [
          410,
          185
        ],
        [
          264,
          185
        ]
      ],
      "text": "Oslo",
      "text_confidence": 0.8
    }
  ],
  "attention_gif": "predict/example_line.gif"
}

Predict with an external n-gram language model

This example assumes that you have already trained a language model.

!!! note - the weight parameter defines how much weight to give to the language model. It should be set carefully (usually between 0.5 and 2.0) as it will affect the quality of the predictions. - linebreaks are treated as spaces by language models, as a result predictions will not include linebreaks.

Language model at character level

Update the parameters.yml file obtained during DAN training.

parameters:
  ...
  language_model:
    model: my_dataset/language_model/model_characters.arpa
    lexicon: my_dataset/language_model/lexicon_characters.txt
    tokens: my_dataset/language_model/tokens.txt
    weight: 0.5

Then, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --use-language-model \
    --output predict_char_lm/

It will create the following JSON file named after the image in the predict_char_lm folder:

{
  "text": "etc., some jeg netop idag\nholder Vask paa.\nLeien af Skj\u00f8rterne\nbestad i at jeg kj\u00f8bte\net Forkl\u00e6de til hver\naf de to Piger, some\nhavde laant os dem.\nResten var Vask af Hardan-\ngerskj\u00f8rter og et Forkl\u00e6de,\nsamt Fragt paa det Gods\n(N\u00f8i) some man sendte\nmig ubet\u00e6lt.\nIdag fik jeg hyggeligt\nFrimarkebrev fra Fosvold\nMed Hilsen\nDeres\nHulda Garborg",
  "language_model": {
    "text": "eet., some jeg netop idag holder Vask paa. Leien af Skj\u00f8rterne bestad i at jeg kj\u00f8bte et Forkl\u00e6de til hver af de to Piger, some havde laant os dem. Resten var Vask af Hardan- gerskj\u00f8rter og et Forkl\u00e6de, samt Fragt paa det Gods (T\u00f8i) some man sendte mig ubet\u00e6lt. Idag fik jeg hyggeligt Frimarkebrev fra Fosvold Med Hilsen Deres Hulda Garborg",
    "confidence": 0.9
  }
}

Language model at subword level

Update the parameters.yml file obtained during DAN training.

parameters:
  ...
  language_model:
    model: my_dataset/language_model/model_subwords.arpa
    lexicon: my_dataset/language_model/lexicon_subwords.txt
    tokens: my_dataset/language_model/tokens.txt
    weight: 0.5

Then, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --use-language-model \
    --output predict_subword_lm

It will create the following JSON file named after the image in the predict_subword_lm folder:

{
  "text": "etc., some jeg netop idag\nholder Vask paa.\nLeien af Skj\u00f8rterne\nbestad i at jeg kj\u00f8bte\net Forkl\u00e6de til hver\naf de to Piger, some\nhavde laant os dem.\nResten var Vask af Hardan-\ngerskj\u00f8rter og et Forkl\u00e6de,\nsamt Fragt paa det Gods\n(N\u00f8i) some man sendte\nmig ubet\u00e6lt.\nIdag fik jeg hyggeligt\nFrimarkebrev fra Fosvold\nMed Hilsen\nDeres\nHulda Garborg",
  "language_model": {
    "text": "eet., some jeg netop idag holder Vask paa. Leien af Skj\u00f8rterne bestad i at jeg kj\u00f8bte et Forkl\u00e6de til hver af de to Piger, some havde laant os dem. Resten var Vask af Hardan- gerskj\u00f8rter og et Forkl\u00e6de, samt Fragt paa det Gods (T\u00f8i) some man sendte mig ubet\u00e6lt. Idag fik jeg hyggeligt Frim\u00e6rkebrev fra Fosvold Med Hilsen Deres Hulda Garborg",
    "confidence": 0.84
  }
}

Language model at word level

Update the parameters.yml file obtained during DAN training.

parameters:
  ...
  language_model:
    model: my_dataset/language_model/model_words.arpa
    lexicon: my_dataset/language_model/lexicon_words.txt
    tokens: my_dataset/language_model/tokens.txt
    weight: 0.5

Then, run this command:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --use-language-model \
    --output predict_word_lm/

It will create the following JSON file named after the image in the predict_word_lm folder:

{
  "text": "etc., some jeg netop idag\nholder Vask paa.\nLeien af Skj\u00f8rterne\nbestad i at jeg kj\u00f8bte\net Forkl\u00e6de til hver\naf de to Piger, some\nhavde laant os dem.\nResten var Vask af Hardan-\ngerskj\u00f8rter og et Forkl\u00e6de,\nsamt Fragt paa det Gods\n(N\u00f8i) some man sendte\nmig ubet\u00e6lt.\nIdag fik jeg hyggeligt\nFrimarkebrev fra Fosvold\nMed Hilsen\nDeres\nHulda Garborg",
  "language_model": {
    "text": "etc., some jeg netop idag holder Vask paa. Leien af Skj\u00f8rterne bestad i at jeg kj\u00f8bte et Forkl\u00e6de til hver af de to Piger, some havde laant os dem. Resten var Vask af Hardan- gerskj\u00f8rter og et Forkl\u00e6de, samt Fragt paa det Gods (T\u00f8i) some man sendte mig ubetalt. Idag fik jeg hyggeligt Frim\u00e6rkebrev fra Fosvold Med Hilsen Deres Hulda Garborg",
    "confidence": 0.77
  }
}

Speed up prediction with model compilation

To speed up prediction, it is recommended to compile models using torch.compile.

Run this command to use this option:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --compile-model

When predicting on images of variable size, it is recommended to enable the dynamic mode:

teklia-dan predict \
    --image-dir images/ \
    --model models \
    --output predict/ \
    --compile-model \
    --dynamic-mode