<commit_before>.. _advanced:

Advanced Usage
==============

Optical character recognition is the serial execution of multiple steps, in the
case of kraken, layout analysis/page segmentation (extracting topological text
lines from an image), recognition (feeding text lines images into a
classifier), and finally serialization of results into an appropriate format
such as ALTO or PageXML.

Input Specification
-------------------

Kraken inputs and their outputs can be defined in multiple ways. The most
simple are input-output pairs, i.e. producing one output document for one input
document follow the basic syntax:

.. code-block:: console

        $ kraken -i input_1 output_1 -i input_2 output_2 ... subcommand_1 subcommand_2 ... subcommand_n

In particular subcommands may be chained.

There are other ways to define inputs and outputs as the syntax shown above can
become rather cumbersome for large amounts of files.

As such there are a couple of ways to deal with multiple files in a compact
way. The first is batch processing:

.. code-block:: console

        $ kraken -I '*.png' -o ocr.txt segment ...

which expands the `glob expression
<https://en.wikipedia.org/wiki/Glob_(programming)>`_ in kraken internally and
appends the suffix defined with `-o` to each output file. An input file
`xyz.png` will therefore produce an output file `xyz.png.ocr.txt`. A second way
is to input multi-image files directly. These can be either in PDF, TIFF, or
JPEG2000 format and are specified like:

.. code-block:: console

        $ kraken -I some.pdf -o ocr.txt -f pdf segment ...

This will internally extract all page images from the input PDF file and write
one output file with an index (can be changed using the `-p` option) and the
suffix defined with `-o`.

The `-f` option can not only be used to extract data from PDF/TIFF/JPEG2000
files but also various XML formats. In these cases the appropriate data is
automatically selected from the inputs, image data for segmentation or line and
region segmentation for recognition:

.. code-block:: console

        $ kraken -i alto.xml alto.ocr.txt -i page.xml page.ocr.txt -f xml ocr ...

The code is able to automatically determine if a file is in PageXML or ALTO format.

Binarization
------------

.. _binarization:

.. note::

   Binarization is deprecated and mostly not necessary anymore. It can often
   worsen text recognition results especially for documents with uneven
   lighting, faint writing, etc.

The binarization subcommand converts a color or grayscale input image into an
image containing only two color levels: white (background) and black
(foreground, i.e. text). It accepts almost the same parameters as
``ocropus-nlbin``. Only options not related to binarization, e.g. skew
detection are missing. In addition, error checking (image sizes, inversion
detection, grayscale enforcement) is always disabled and kraken will happily
binarize any image that is thrown at it.

Available parameters are:

===========     ====
option          type
===========     ==== 
--threshold     FLOAT
--zoom          FLOAT
--escale        FLOAT
--border        FLOAT
--perc          INTEGER RANGE
--range         INTEGER
--low           INTEGER RANGE
--high          INTEGER RANGE
===========     ====

To binarize a image:

.. code-block:: console

        $ kraken -i input.jpg bw.png binarize

.. note::

        Some image formats, notably JPEG, do not support a black and white
        image mode. Per default the output format according to the output file
        name extension will be honored. If this is not possible, a warning will
        be printed and the output forced to PNG:

        .. code-block:: console

                $ kraken -i input.jpg bw.jpg binarize
                Binarizing	[06/24/22 09:56:23] WARNING  jpeg does not support 1bpp images. Forcing to png.
                ✓

Page Segmentation 
-----------------

The `segment` subcommand accesses page segmentation into lines and regions with
the two layout analysis methods implemented: the trainable baseline segmenter
that is capable of detecting both lines of different types and regions and a
legacy non-trainable segmenter that produces bounding boxes. 

Universal parameters of either segmenter are:

=============================================== ======
option                                          action
=============================================== ======
-d, --text-direction                            Sets principal text direction. Valid values are `horizontal-lr`, `horizontal-rl`, `vertical-lr`, and `vertical-rl`.
-m, --mask                                      Segmentation mask suppressing page areas for line detection. A simple black and white mask image where 0-valued (black) areas are ignored for segmentation purposes.
=============================================== ======

Baseline Segmentation
^^^^^^^^^^^^^^^^^^^^^

The baseline segmenter works by applying a segmentation model on a page image
which labels each pixel on the image with one or more classes with each class
corresponding to a line or region of a specific type. In addition there are two
auxilary classes that are used to determine the line orientation. A simplified
example of a composite image of the auxilary classes and a single line type
without regions can be seen below:

.. image:: _static/blla_heatmap.jpg
  :width: 800
  :alt: BLLA output heatmap

In a second step the raw heatmap is vectorized to extract line instances and
region boundaries, followed by bounding polygon computation for the baselines,
and text line ordering. The final output can be visualized as:

.. image:: _static/blla_output.jpg
  :width: 800
  :alt: BLLA final output 

The primary determinant of segmentation quality is the segmentation model
employed. There is a default model that works reasonably well on printed and
handwritten material on undegraded, even writing surfaces such as paper or
parchment. The output of this model consists of a single line type and a
generic text region class that denotes coherent blocks of text. This model is
employed automatically when the baseline segment is activated with the `-bl`
option:

.. code-block:: console
<commit_msg>Fix new typos in documentation (found by codespell)<commit_after>.. _advanced:

Advanced Usage
==============

Optical character recognition is the serial execution of multiple steps, in the
case of kraken, layout analysis/page segmentation (extracting topological text
lines from an image), recognition (feeding text lines images into a
classifier), and finally serialization of results into an appropriate format
such as ALTO or PageXML.

Input Specification
-------------------

Kraken inputs and their outputs can be defined in multiple ways. The most
simple are input-output pairs, i.e. producing one output document for one input
document follow the basic syntax:

.. code-block:: console

        $ kraken -i input_1 output_1 -i input_2 output_2 ... subcommand_1 subcommand_2 ... subcommand_n

In particular subcommands may be chained.

There are other ways to define inputs and outputs as the syntax shown above can
become rather cumbersome for large amounts of files.

As such there are a couple of ways to deal with multiple files in a compact
way. The first is batch processing:

.. code-block:: console

        $ kraken -I '*.png' -o ocr.txt segment ...

which expands the `glob expression
<https://en.wikipedia.org/wiki/Glob_(programming)>`_ in kraken internally and
appends the suffix defined with `-o` to each output file. An input file
`xyz.png` will therefore produce an output file `xyz.png.ocr.txt`. A second way
is to input multi-image files directly. These can be either in PDF, TIFF, or
JPEG2000 format and are specified like:

.. code-block:: console

        $ kraken -I some.pdf -o ocr.txt -f pdf segment ...

This will internally extract all page images from the input PDF file and write
one output file with an index (can be changed using the `-p` option) and the
suffix defined with `-o`.

The `-f` option can not only be used to extract data from PDF/TIFF/JPEG2000
files but also various XML formats. In these cases the appropriate data is
automatically selected from the inputs, image data for segmentation or line and
region segmentation for recognition:

.. code-block:: console

        $ kraken -i alto.xml alto.ocr.txt -i page.xml page.ocr.txt -f xml ocr ...

The code is able to automatically determine if a file is in PageXML or ALTO format.

Binarization
------------

.. _binarization:

.. note::

   Binarization is deprecated and mostly not necessary anymore. It can often
   worsen text recognition results especially for documents with uneven
   lighting, faint writing, etc.

The binarization subcommand converts a color or grayscale input image into an
image containing only two color levels: white (background) and black
(foreground, i.e. text). It accepts almost the same parameters as
``ocropus-nlbin``. Only options not related to binarization, e.g. skew
detection are missing. In addition, error checking (image sizes, inversion
detection, grayscale enforcement) is always disabled and kraken will happily
binarize any image that is thrown at it.

Available parameters are:

===========     ====
option          type
===========     ==== 
--threshold     FLOAT
--zoom          FLOAT
--escale        FLOAT
--border        FLOAT
--perc          INTEGER RANGE
--range         INTEGER
--low           INTEGER RANGE
--high          INTEGER RANGE
===========     ====

To binarize a image:

.. code-block:: console

        $ kraken -i input.jpg bw.png binarize

.. note::

        Some image formats, notably JPEG, do not support a black and white
        image mode. Per default the output format according to the output file
        name extension will be honored. If this is not possible, a warning will
        be printed and the output forced to PNG:

        .. code-block:: console

                $ kraken -i input.jpg bw.jpg binarize
                Binarizing	[06/24/22 09:56:23] WARNING  jpeg does not support 1bpp images. Forcing to png.
                ✓

Page Segmentation 
-----------------

The `segment` subcommand accesses page segmentation into lines and regions with
the two layout analysis methods implemented: the trainable baseline segmenter
that is capable of detecting both lines of different types and regions and a
legacy non-trainable segmenter that produces bounding boxes. 

Universal parameters of either segmenter are:

=============================================== ======
option                                          action
=============================================== ======
-d, --text-direction                            Sets principal text direction. Valid values are `horizontal-lr`, `horizontal-rl`, `vertical-lr`, and `vertical-rl`.
-m, --mask                                      Segmentation mask suppressing page areas for line detection. A simple black and white mask image where 0-valued (black) areas are ignored for segmentation purposes.
=============================================== ======

Baseline Segmentation
^^^^^^^^^^^^^^^^^^^^^

The baseline segmenter works by applying a segmentation model on a page image
which labels each pixel on the image with one or more classes with each class
corresponding to a line or region of a specific type. In addition there are two
auxiliary classes that are used to determine the line orientation. A simplified
example of a composite image of the auxiliary classes and a single line type
without regions can be seen below:

.. image:: _static/blla_heatmap.jpg
  :width: 800
  :alt: BLLA output heatmap

In a second step the raw heatmap is vectorized to extract line instances and
region boundaries, followed by bounding polygon computation for the baselines,
and text line ordering. The final output can be visualized as:

.. image:: _static/blla_output.jpg
  :width: 800
  :alt: BLLA final output 

The primary determinant of segmentation quality is the segmentation model
employed. There is a default model that works reasonably well on printed and
handwritten material on undegraded, even writing surfaces such as paper or
parchment. The output of this model consists of a single line type and a
generic text region class that denotes coherent blocks of text. This model is
employed automatically when the baseline segment is activated with the `-bl`
option:

.. code-block:: console

{'fraction_non_alphanumeric': 0.09542967492758288, 'fraction_numerical': 0.0054715159317669775, 'mean_word_length': 3.265271105010295, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3466059', 'n_tokens_mistral': 3211, 'n_tokens_neox': 2986, 'n_words': 1635}