Reading Text
One reading, on demand. Nothing happens until a client writes <module>/read-text/execute.
What a run does
-
Refuses the call if this module is already busy (status code
-1). -
Clears the previous reading, so a failure never leaves old text behind.
-
Checks every setting and reports all the problems at once.
-
Reads the image from
input/input-image-address. -
Applies
input/crop. -
Runs the OCR engine and publishes the text.
The settings
| Node | Default | What it does |
|---|---|---|
|
(empty) |
Address of the image node to read, e.g.
|
|
0 |
The part of the image to read. All zero reads the whole image; a zero width or height reaches the right or bottom edge. Crop tight around the text - see Reading Accurately. |
|
|
Which language model to read with. The models installed on this device are listed on
|
|
|
|
|
|
How much structure to look for in the image. |
|
|
What is done to the image before it is read. Reach for |
|
|
Which characters may be returned. |
|
|
The confidence a word must reach to be reported, between 0 and 1. |
Reading the result
output/result is a text_read_result flatbuffer.
| Field | Meaning |
|---|---|
|
The whole reading exactly as the engine produced it, lines separated by newlines. Not filtered by
|
|
One recognised word, its confidence from 0 to 1, and a box around it in the coordinates of the region that was read. |
|
How many words are reported. |
|
Average confidence over the reported words; 0 when there are none. |
|
The threshold that was applied, so a short word list reads as "strict" rather than "bad image". |
|
The language actually used - not always the one asked for. |
|
As actually used. |
|
The region that was read - the whole image unless a crop was set. |
|
Microseconds since the epoch, when the reading finished. |
text and words[] can disagree, on purpose
text is the engine’s own output, with the line breaks it found. words[] is filtered by
min-score. With min-score at 0.8, a word the engine reported at 0.4 appears in text and not
in words[].
If you need them to agree, read text only when word_count is the number you expected.
When it fails
| Situation | Status code | What you get |
|---|---|---|
Another operation on this module is running |
|
Nothing done; the previous reading is left alone |
Any setting is unusable |
|
Every problem named in one |
The image node cannot be read |
|
Empty result |
The crop does not fit the image |
|
Empty result |
The OCR engine could not start |
|
Empty result, with the reason in |
Nothing readable in the image |
|
Empty text, |
The last two rows are the distinction that matters most in production: a reader that could not start
reports -7 and says why, while a working reader looking at a blank part reports success with no
words. They used to be indistinguishable.