# EasyDeepOCR - Reading Texts with Deep Learning
## Purpose
**EasyDeepOCR** is a new generation OCR library that relies on deep learning technologies to tackle modern text reading challenges.
**EasyDeepOCR** features:
* Zero-configuration text location and recognition
* Text filtering through [topologies](detailed_usage.html.md#edo-specifying-topology)
* Improved speed on x86_64 CPUs with **OpenVINO** and **NVIDIA** GPUs with **TensorRT**
* Optional further speed optimization using only a few labeled samples
* A simple and comprehensive C++, C# and Python API
* A fully featured **eVision Studio** tool and samples showcasing the entire workflow of **EasyDeepOCR**.
**EasyDeepOCR** is a major improvement over the **EasyOCR** and **EasyOCR2** libraries, combining ease of use and enhanced capabilities.
### Scope
**EasyDeepOCR** is able to locate and read all texts in a given image, provided they adhere to the following specifications:
* Printable ASCII characters: `!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~`
* Industrial fonts
* Minimum line height: 12 pixels
* Line aspect ratio between 1:1 and 40:1
* Maximum characters per line: 50
* Gray scale (8-bit) or color (24-bit) images
* Near planar images (limited perspective)
### Structured Texts
When you specify a topology, the lines are gathered into texts that satisfy the following requirements:
* The texts match the topology.
* The texts are structured.
#### HINT
See [Specifying the Execution Settings](setting_the_parameters.html.md#edo-specifying-execution-settings).
**EasyDeepOCR** only returns ‘structured texts’ (a concept specific to this tool: see [`eVision::EasyDeepOCR::ETextLine`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextLine.html) [.NET](../../../doxygen_cs/classeVision_1_1EasyDeepOCR_1_1ETextLine.html) [Python](../../../doxygen_python/classeVision_1_1EasyDeepOCR_1_1ETextLine.html)) where the geometric arrangement of lines and words meets a particular definition:
1. All the lines of a ‘structured text’:
* Must be parallel.
* Must have the same height.
* Must be horizontally aligned:
\\\\
Two lines l₀ and l₁ are horizontally aligned if:
$$
l₀^{begin} \le l₁^{begin}
and
l₁^{end} \le l₀^{end}
$$
2. All the pairs of consecutive lines:
* Must not overlap vertically.
* Must not be separated by a vertical distance greater than the line height.
3. All the words of a line:
* Must not be separated by a horizontal distance greater than the line height.
| |  |  |
|----------------------|--------------------------------------------------------------------|---------------------------------------------------------------------|
| Parallelism |  |  |
| Line height |  |  |
| Horizontal alignment |  |  |
| Vertical alignment |  |  |
| Word spacing |  |  |
### Optimization for Custom Use Cases
**EasyDeepOCR** also offers the possibility to optimize the reader for a custom use case.
* When doing so, an additional constraint is added to the list:
* The texts must belong to the same custom use case as the one used for the optimization.
* This optimization offers two potential benefits:
* Increasing the processing speed.
* Improving the detection of challenging texts.
* In the context of **EasyDeepOCR**, a *custom use case* is defined as follows:
* It is a batch of images captured in the same conditions that depict a different instance of the same object.
* For every image, you must designate a ‘text of interest’.
* This ‘text of interest’ is the text that the `ETextReader` should retrieve.
* From one image to another, all the ‘texts of interest’ must share some geometrical properties.
\\\\
Specifically, they must have:
* The same line height (in pixels).
* The same font.
* The same appearance (such as printed, embossed, dotted).
#### NOTE
There can be several ‘texts of interest’ in a given image, but all texts must share the above-mentioned geometrical properties.
## Basic Workflow
The full-featured **EasyDeepOCR** workflow consists of the following steps:
1. Instantiate an [`ETextReader`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextReader.html) [.NET](../../../doxygen_cs/classeVision_1_1EasyDeepOCR_1_1ETextReader.html) [Python](../../../doxygen_python/classeVision_1_1EasyDeepOCR_1_1ETextReader.html)
2. (Optional) Set the [`EDeepLearningExecutionSettings`](../../../doxygen_cpp/classeVision_1_1EasyDeepLearning_1_1EDeepLearningExecutionSettings.html) [.NET](../../../doxygen_cs/classeVision_1_1EasyDeepLearning_1_1EDeepLearningExecutionSettings.html) [Python](../../../doxygen_python/classeVision_1_1EasyDeepLearning_1_1EDeepLearningExecutionSettings.html)
3. Initialize
4. (Optional) Set the [`ETopology`](../../../doxygen_cpp/classeVision_1_1ETopology.html) [.NET](../../../doxygen_cs/classeVision_1_1ETopology.html) [Python](../../../doxygen_python/classeVision_1_1ETopology.html)
5. (Optional) Optimize
6. Read
7. Extract the [`EasyDeepOCR::EText`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1EText.html) [.NET](../../../doxygen_cs/classeVision_1_1EasyDeepOCR_1_1EText.html) [Python](../../../doxygen_python/classeVision_1_1EasyDeepOCR_1_1EText.html) results
This complete workflow is broken down and explained in the following sections:
* The section [Reading a Text](detailed_usage.html.md#edo-reading-a-text) goes through the minimal working example, without any optional steps.
* The section [Specifying a Topology](detailed_usage.html.md#edo-specifying-topology) explains how to create the appropriate topology for your use case.
* The section [Performing an Optimization](detailed_usage.html.md#edo-performing-optimization) demonstrates how to optimize the reader for a given use case.
* Finally, the section [Specifying the Execution Settings](setting_the_parameters.html.md#edo-specifying-execution-settings) explains how to properly set the deep learning execution settings.
### Inputs
The reading method of an [`ETextReader`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextReader.html), namely [`ETextReader::Read()`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextReader.html#a89af65e87d9b4bcb08c67ccb6144bef6), accepts 2 input arguments:
* An ROI ([`EROIBW8`](../../../doxygen_cpp/classeVision_1_1EROIBW8.html) or [`EROIC24`](../../../doxygen_cpp/classeVision_1_1EROIC24.html)): the image to be searched for texts.
* An [`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) (optionally) that defines a geometrical filter: any text whose 4 corners are not included in the region is filtered out.
### Outputs
The method [`ETextReader::Read()`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextReader.html#a89af65e87d9b4bcb08c67ccb6144bef6) returns a vector of [`EText`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1EText.html) that contains the following information:
* An [`ERectangle`](../../../doxygen_cpp/classeVision_1_1ERectangle.html) representing the text position in the image
* A text string
* A vector of [`ETextLine`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextLine.html)
This vector of [`ETextLine`](../../../doxygen_cpp/classeVision_1_1EasyDeepOCR_1_1ETextLine.html) represents the lines of the text and contains 2 pieces of information:
* An [`ERectangle`](../../../doxygen_cpp/classeVision_1_1ERectangle.html) representing the line position in the image
* A line string