# Using EasyOCR2
## Detecting the Characters
**EasyOCR2** first segment pixels to detect the blobs in an image. It then places textboxes over the detected blobs following a user-defined topology specifying the number of lines, words and characters in the text (see [Setting the Topology]()).
You can specify a character type (letter, digit and/or symbol) for each character in the text, to improve the recognition rate and speed.
To find characters in an image:
### C++
```cpp
#include
```
```cpp
using namespace eVision;
// Load an Image
EImageBW8 image;
image.Load("image.tif");
// Attach a ROI to the image
EROIBW8 roi;
roi.Attach(&image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2;
// Enable the topology usage
ocr2.SetEnabledTopology(true);
// Set the expected character sizes
ocr2.SetCharsWidthRange(EIntegerRange(25, 25));
ocr2.SetCharsHeight(37);
// Set the text polarity, in this case WhiteOnBlack
ocr2.SetTextPolarity(EasyOCR2TextPolarity_WhiteOnBlack);
// Set the topology
ocr2.SetTopology(".{10}\n.{3} .{4}");
// Detect the text in the image. The output Text structure contains:
// - an individual textbox for each character
// - an individual bitmap image for each character
// - a threshold value to binarize the bitmap image for each character
// All structured in a hierarchy with Lines -> Words -> Characters
EOCR2Text text = ocr2.Detect(roi);
```
### C#
```cs
using eVision;
```
```cs
// Load an Image
EImageBW8 image = new EImageBW8();
image.Load("image.tif");
// Attach a ROI to the image
EROIBW8 roi = new EROIBW8();
roi.Attach(image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2 = new EOCR2();
// Enable the topology usage
ocr2.EnabledTopology = true;
// Set the expected character sizes
ocr2.CharsWidthRange = new EIntegerRange(25, 25);
ocr2.CharsHeight = 37;
// Set the text polarity, in this case WhiteOnBlack
ocr2.TextPolarity = EasyOCR2TextPolarity.WhiteOnBlack;
// Set the topology
ocr2.Topology = ".{10}\n.{3} .{4}";
// Detect the text in the image. The output Text structure contains:
// - an individual textbox for each character
// - an individual bitmap image for each character
// - a threshold value to binarize the bitmap image for each character
// All structured in a hierarchy with Lines –> Words -> Characters
EOCR2Text text = ocr2.Detect(roi);
```
### Python
```py
import eVision
# Load an Image
image = eVision.EImageBW8()
image.Load("image.tif")
# Attach a ROI to the image
roi = eVision.EROIBW8()
roi.Attach(image, 50, 224, 340, 96)
# Create an EOCR2 instance
ocr2 = eVision.EOCR2()
# Enable the topology usage
ocr2.EnabledTopology = True;
# Set the expected character sizes
ocr2.CharsWidthRange = eVision.EIntegerRange(25, 25)
ocr2.CharsHeight = 37
# Set the text polarity, in this case WhiteOnBlack
ocr2.TextPolarity = eVision.EasyOCR2TextPolarity.WhiteOnBlack
# Set the topology
ocr2.Topology = ".{10}\n.{3} .{4}"
# Detect the text in the image. The output Text structure contains:
# - an individual textbox for each character
# - an individual bitmap image for each character
# - a threshold value to binarize the bitmap image for each character
# All structured in a hierarchy with Lines -> Words -> Characters
text = ocr2.Detect(roi)
```
#### HINT
Don’t forget to setup the parameters:
* Mandatory: Set the characters [`WidthRange`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#ae23c36b1dfb61cff3b638137b7aa49ea) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a9f113649faad0ba96ee08cd6a9e5f2b4) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#ab53558b356b1a5bea99c546afd036bf6), [`Height`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a746aa29c47ac97e8ce97b94a4bb5d8eb) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#ab0b343d5ee166210cfd5353a4d1d6ea3) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a5ecbc70d7d58be654a406560772167b7), [`Polarity`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a177abcbfb209017d2e0ea90b999713da) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a0ce6e8d5b1692b8816508f15ecd1d297) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#ae9be66d9be0378116742cb560cf97275).
* Optional: [Segmentation Parameters](setting_the_parameters.html.md#easyocr2-segmentation-parameters), [Detection Parameters](setting_the_parameters.html.md#easyocr2-detection-parameters) or [No Topology Parameters](setting_the_parameters.html.md#easyocr2-no-topology-parameter).
#### HINT
* The detection returns an [`EOCR2Text`](../../../doxygen_cpp/classeVision_1_1EOCR2Text.html) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Text.html) [Python](../../../doxygen_python/classeVision_1_1EOCR2Text.html) structure that contains a textbox and a bitmap image for each character.
* Hierarchically stored inside are: [`Lines`](../../../doxygen_cpp/classeVision_1_1EOCR2Line.html) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Line.html) [Python](../../../doxygen_python/classeVision_1_1EOCR2Line.html), [`Words`](../../../doxygen_cpp/classeVision_1_1EOCR2Word.html) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Word.html) [Python](../../../doxygen_python/classeVision_1_1EOCR2Word.html) and [`Characters`](../../../doxygen_cpp/classeVision_1_1EOCR2Char.html) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Char.html) [Python](../../../doxygen_python/classeVision_1_1EOCR2Char.html).
#### SEE ALSO
* **EasyOCR2** extracts the pixels inside each character box from the image.
* Setting the topology is optional see [Setting a Topology]().
* Use the resulting character-images to perform:
* [Learning the Characters]()
* [Recognizing the Characters]()
## Setting a Topology
The parameter ([`Topology`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#af1a7a1dd9df4f5af15954b0a48d49e3a) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a36aa5b8c221c2898b8881ce533e26da1) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a393eb80fe7989af657db0f8e632db299)) specifies the structure of the text (number of lines, words and characters) as well as the type of characters in the text.
#### NOTE
* The box-fitting method uses this parameter to fit the textboxes to the detected blobs.
* The recognition method limits the number of candidates for each character based on the topology.
* The topology uses the following modified regular expression (Regex) wildcards:
* **“.” (dot)** represents any character (not including a space).
* **“L”** represents an alphabetic character:
* **“Lu”** represents an uppercase alphabetic character.
* **“Ll”** represents a lowercase alphabetic character.
* **“N”** represents a digit.
* **“P”** represents a punctuation character among: `! “ \# % & ‘ ( ) \* , - . / : ; \< \> ? @ \[ \\ \] \_ { \| } ~`
* **“S”** represents a symbol among: `\$ + - \< = \> \| ~`
* **“\\n”** represents a line break.
* **“ ” (space)** represents a space between two words.
* You can *combine* these wildcards.
* For example: [LN] represents an alphanumeric character.
* To specify *multiple characters*:
* Add **{n}** at the end for n characters.
* If the amount of characters is uncertain, specify {n,m} for a minimum of n characters and a maximum of m characters.
#### WARNING
* Some character types are not recognized when using pretrained classifiers:
* Only **“Lu“**, **“N“** and **“P“** are supported.
* Using **“.“** in your topology only results in a character that is either a uppercase letter, a number or a punctuation character.
* Using **“L“** only results in an uppercase letter.
* Using another character type throws an exception.
Represents a text comprised of 2 lines:
* The first line has 1 word:
* The word has 3 to 5 uppercase alphanumeric characters followed by a punctuation character and 4 digits.
* The second line has 2 words:
* The first word has 5 characters (of any type).
* The second word has 2 letters (upper- or lowercase).
Represents a text with 2 lines:
* The first line has 2 words:
* The first word has 3 uppercase letters followed by a punctuation mark.
* The second word has 6 digits.
* The second line also has two words:
* The first word has 3 uppercase letters followed by a punctuation mark.
* The second word has 2 digits, followed by a punctuation mark and 4 digits.
Represents a text with 4 lines:
* The first line contains 1 word of 10 characters (of any type).
* The second line contains 1 word of 7 characters
* The third line contains 2 words, each of 5 characters.
* The fourth line contains 2 words of 5 and 7 characters respectively.
## Learning the Characters
In order to recognize characters, **EasyOCR2** there are two modes: Using the pre-trained classifier, or learning the characters from reference data.
To use a database of known characters, you can either generate it from images and/or from TrueType system fonts.
* To learn from the detected characters in your image as described in [Detecting the Characters]():
### C++
```cpp
#include
```
```cpp
using namespace eVision;
// Load an Image
EImageBW8 image;
image.Load("image.tif");
// Attach a ROI to the image
EROIBW8 roi;
roi.Attach(&image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2;
// Enable the topology usage
ocr2.SetEnabledTopology(true);
// Set the required parameters
ocr2.SetCharsWidthRange(EIntegerRange(25, 25));
ocr2.SetCharsHeight(37);
ocr2.SetTextPolarity(EasyOCR2TextPolarity_WhiteOnBlack);
ocr2.SetTopology(".{10}\n.{3} .{4}");
// Learn from the reference image:
// 1) Detect the text in the image
EOCR2Text text = ocr2.Detect(roi);
// 2) Set the true values of the text
text.SetText("Bt121KPJ80\n786 9512");
// 3) Add the characters to the character database
ocr2.Learn(text);
// Save the character database
ocr2.SaveCharacterDatabase("myDB.o2d");
// Alternatively, save the model file.
// This will store the character database and the parameter settings
ocr2.Save("myModel.o2m");
```
### C#
```cs
using eVision;
```
```cs
// Load an Image
EImageBW8 image = new EImageBW8();
image.Load("image.tif");
// Attach a ROI to the image
EROIBW8 roi = new EROIBW8();
roi.Attach(image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2 = new EOCR2();
// Enable the topology usage
ocr2.EnabledTopology = true;
// Set the required parameters
ocr2.CharsWidthRange = new EIntegerRange(25, 25);
ocr2.CharsHeight = 37;
ocr2.TextPolarity = EasyOCR2TextPolarity.WhiteOnBlack;
ocr2.Topology = ".{10}\n.{3} .{4}";
// Learn from the reference image:
// 1) Detect the text in the image
EOCR2Text text = ocr2.Detect(roi);
// 2) Set the true values of the text
text.Text = "Bt121KPJ80\n786 9512";
// 3) Add the characters to the character database
ocr2.Learn(text);
// Save the character database
ocr2.SaveCharacterDatabase("myDB.o2d");
// Alternatively, save the model file.
// This will store the character database and the parameter settings
ocr2.Save("myModel.o2m");
```
### Python
```py
import eVision
# Load an Image
image = eVision.EImageBW8()
image.Load("image.tif")
# Attach a ROI to the image
roi = eVision.EROIBW8()
roi.Attach(image, 50, 224, 340, 96)
# Create an EOCR2 instance
ocr2 = eVision.EOCR2()
# Enable the topology usage
ocr2.EnabledTopology = True;
# Set the required parameters
ocr2.CharsWidthRange = eVision.EIntegerRange(25, 25)
ocr2.CharsHeight = 37
ocr2.TextPolarity = eVision.EasyOCR2TextPolarity.WhiteOnBlack
ocr2.Topology = ".{10}\n.{3} .{4}"
# Learn from the reference image:
# 1) Detect the text in the image
text = ocr2.Detect(roi)
# 2) Set the true values of the text
text.Text = "Bt121KPJ80\n786 9512"
# 3) Add the characters to the character database
ocr2.Learn(text)
# Save the character database
ocr2.SaveCharacterDatabase("myDB.o2d")
# Alternatively, save the model file.
# This will store the character database and the parameter settings
ocr2.Save("myModel.o2m")
```
#### HINT
Alternatively, you can [`Save`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#af9c396e4e6a822efa380f66dbcf2832b) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#aafb875fab1b49784e9a35cb3e3ca3d80) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a6d1f7d9402586aca101fe3159c91e9e6), [`SaveCharacterDatabase`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#adee7473630720b47cf9b12e2c5c42db3) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a187b0d9bba20dbb2ddf61e79fde8eb07) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a2b2aaf79ceea2fe033d91e68f8418391) for more informations.
#### SEE ALSO
[`SetText`](../../../doxygen_cpp/classeVision_1_1EOCR2Text.html#ac203bdb4a4baec90e60b9595609dba15) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Text.html#acbc9c77a01c68966fcbcfed3542a172c) [Python](../../../doxygen_python/classeVision_1_1EOCR2Text.html#adc774a728005d2c84db39390449d2852), \* [`Learn`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#aed12fa1f3524e35d0df6292fc069ac26) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a3c6c8b30e161f5d02db4bd040d4cd81c) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#ae88e55677b08ed970ac0f1de3da6f620),
* To learn directly from a True Type font instead:
* Use [`AddCharactersToDatabase`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#ae3b50c1e6b1c632972df05e69de1d3a8) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#afc6fd47120cc94de4a30f622a07f6611) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a57763de63ad327697c9fc20e349acf92) with the path to the True Type font to learn its characters.
#### HINT
* Use [`ClearCharacterDatabase`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a6f01383bc15e55ce2323214399351fbb) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#a0230d8e7014e8eecee625e4522e7cb4d) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a7adbb62ab44ca3e5f9ac49cdee133ab8) to clear the current character database and remove all characters in it.
## Recognizing the Characters
To recognize characters, **EasyOCR2** uses a pretrained classifier or a classifier that you trained on your character database.
For each input character:
* The classifier calculates a score for all candidate outputs.
* It returns the candidate with the highest score as the recognition result.
Use a **topology** to pass information to the classifier about each character. This reduces the number of candidates and improves the recognition rate (see [Setting the Topology]()).
To recognize the characters detected as described in [Detecting the Characters]() and learned as described in [Learning the Characters]():
### C++
```cpp
#include
```
```cpp
using namespace eVision;
// Load an image
EImageBW8 image;
image.Load("image.tif");
// Attach an ROI
EROIBW8 roi;
roi.Attach(&image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2;
// Enable the topology usage
ocr2.SetEnabledTopology(true);
// Set the required parameters
ocr2.SetCharsWidthRange(EIntegerRange(25, 25));
ocr2.SetCharsHeight(37);
ocr2.SetTopology("[LN]{10}\nN{3} N{4}");
ocr2.SetTextPolarity(EasyOCR2TextPolarity_WhiteOnBlack);
// Add a pre-made character database to the EOCR2 instance
ocr2.AddCharactersToDatabase("myDB.o2d");
// Read text from the image
EOCR2Text result = ocr2.Read2(roi);
```
### C#
```cs
using eVision;
```
```cs
// Load an image
EImageBW8 image = new EImageBW8();
image.Load("image.tif");
// Attach an ROI
EROIBW8 roi = new EROIBW8();
roi.Attach(image, 50, 224, 340, 96);
// Create an EOCR2 instance
EOCR2 ocr2 = new EOCR2();
// Enable the topology usage
ocr2.EnabledTopology = true;
// Set the required parameters
ocr2.CharsWidthRange = new EIntegerRange(25, 25);
ocr2.CharsHeight = 37;
ocr2.Topology = "[LN]{10}\nN{3} N{4}";
ocr2.TextPolarity = EasyOCR2TextPolarity.WhiteOnBlack;
// Add a pre-made character database to the EOCR2 instance
ocr2.AddCharactersToDatabase("myDB.o2d");
// Read text from the image
EOCR2Text result = ocr2.Read2(roi);
```
### Python
```py
import eVision
# Load an image
image = eVision.EImageBW8()
image.Load("image.tif")
# Attach an ROI
roi = eVision.EROIBW8()
roi.Attach(image, 50, 224, 340, 96)
# Create an EOCR2 instance
ocr2 = eVision.EOCR2()
# Enable the topology usage
ocr2.EnabledTopology = True;
# Set the required parameters
ocr2.CharsWidthRange = eVision.EIntegerRange(25, 25)
ocr2.CharsHeight = 37
ocr2.Topology = "[LN]{10}\nN{3} N{4}"
ocr2.TextPolarity = eVision.EasyOCR2TextPolarity.WhiteOnBlack
# Add a pre-made character database to the EOCR2 instance
ocr2.AddCharactersToDatabase("myDB.o2d")
# Read text from the image
result = ocr2.Read2(roi)
```
They are two familly of **classifier** to use:
* By default we use the learned character database: [`EOCR2Classifier_DatabaseClassifier`](../../../doxygen_cpp/namespaceeVision.html#a65bd1ecfe5ca244e58f2dd958a8359c8) [.NET](../../../doxygen_cs/namespaceeVision.html#a143fd82a833218e221b0785ffbfa6b0c) [Python](../../../doxygen_python/classeVision_1_1EOCR2Classifier.html).
#### WARNING
When using the DatabaseClassifier, you must specify (either by learning or loading) a character database, else it will read nothing without returning an error.
* Alternatively you can use the pretrained classifier, skipping the learning phase:
* [`EOCR2Classifier_Industrial_A_Z_0_9_P`](../../../doxygen_cpp/namespaceeVision.html#a65bd1ecfe5ca244e58f2dd958a8359c8) [.NET](../../../doxygen_cs/namespaceeVision.html#a143fd82a833218e221b0785ffbfa6b0c) [Python](../../../doxygen_python/classeVision_1_1EOCR2Classifier.html) for industrial context.
* [`EOCR2Classifier_OCRA_A_Z_0_9_P`](../../../doxygen_cpp/namespaceeVision.html#a65bd1ecfe5ca244e58f2dd958a8359c8) [.NET](../../../doxygen_cs/namespaceeVision.html#a143fd82a833218e221b0785ffbfa6b0c) [Python](../../../doxygen_python/classeVision_1_1EOCR2Classifier.html) for the OCR-A font.
* [`EOCR2Classifier_SEMI_A_Z_0_9_P`](../../../doxygen_cpp/namespaceeVision.html#a65bd1ecfe5ca244e58f2dd958a8359c8) [.NET](../../../doxygen_cs/namespaceeVision.html#a143fd82a833218e221b0785ffbfa6b0c) [Python](../../../doxygen_python/classeVision_1_1EOCR2Classifier.html) for the SEMI-OCR font.
#### HINT
* In addition to the detected text, [`EOCR2Text`](../../../doxygen_cpp/classeVision_1_1EOCR2Text.html) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2Text.html) [Python](../../../doxygen_python/classeVision_1_1EOCR2Text.html) objects contain useful additional data:
* The coordinates and the size of each textbox.
* A bitmap image of each textbox.
* A list of the recognition scores for each character.
#### HINT
* Use [`Load`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a138dea91fd2693f20cdc7357a3aa8a7b) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#af8929e0564995e9c01f5c493c82b2a1e) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a25fd46040c828c77dab7eefcaf3ab00b) to read the model (`.o2m`) file from your disk. It contains:
* All the detection parameters,
* The topology,
* The reference character database.
#### SEE ALSO
* [`Detect`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a7b81094564a554e8f20367e06b87b031) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#ad0183f4693ee377414bc235b531d633b) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#aa8bb9cf0068d71113c207494d99d4180) and [`RecognizeText`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a68ff57f016f01c59cb03b5a307ca4df6) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#ad3774ed4d90ef6438aeda3e6b2741c76) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a377006c6628f93292e8736454f74604a) for the two-step process instead of read2.
## Accelerate the Recognition
You can accelerate the character recognition speed using multithreading and/or a GPU.
* With pretrained classifiers, use [`SetMaxNumberOfProcessingThreads`](../../../doxygen_cpp/classeVision_1_1Easy.html#a07daba7dfbeff40db5e1d9e4404d4722) [.NET](../../../doxygen_cs/classeVision_1_1Easy.html#ae729364026373ca376e818d4b82cd978) [Python](../../../doxygen_python/classeVision_1_1Easy.html#ae819b646aea6778997c6155442a0ccee) to multithread the recognition, setting the maximum amount of thread **eVision** can use.
* You can also use a compatible GPU to accelerate even more the recognition.
* Use [`IsGPUAvailable`](../../../doxygen_cpp/classeVision_1_1Easy.html#a060bbd0253fb6542f0bb687d2862bf1f) [.NET](../../../doxygen_cs/classeVision_1_1Easy.html#a7512c0051c8280bfc43fda4e86db7ef3) [Python](../../../doxygen_python/classeVision_1_1Easy.html#af0a6b6342b58160c728e1ac511f69258) to determine if there is a compatible GPU available.
* Use [`SetEnableGPU`](../../../doxygen_cpp/classeVision_1_1EOCR2.html#a070f96a158c2004b155821a54cd1d87c) [.NET](../../../doxygen_cs/classeVision_1_1EOCR2.html#abe00c1dcecf0c233f2ae5ff7ac0b13da) [Python](../../../doxygen_python/classeVision_1_1EOCR2.html#a242ad7e44c686f59fa72e9eba471a37b) to enable the GPU-recognition.