# LumiScan Text Reader 1.1.0.6 – complete documentation

> All pages of the LumiScan Text Reader 1.1.0.6 manual (language: de) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/

# Beschreibung – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/description.html

LumiScan Text Reader liest gedruckten Text aus einem Kamerabild: Teilenummern, Chargencodes, Datumscodes, Etiketten.

Sie richten ihn auf einen Bildknoten, geben an, wo der Text steht und was er enthalten darf, und er meldet den Text zusammen mit einer Konfidenz für jedes Wort.

Er läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC) mit dem ctrlX Data Layer und auf einem PC (Windows 11 oder Ubuntu 24.04) mit LumiScan Keryx, dem Data Layer von HD Vision Systems für PCs. Seine Knoten sind auf beiden gleich, siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/datalayer-reference.html).

Was in jeder LumiScan-App gleich ist - wie Adressen aufgebaut sind, die Aufrufmuster Handshake, Execute und Stream, Statuscodes, Einstellungen und Werkzeuge - ist im Handbuch [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html) beschrieben. Dieses Handbuch behandelt nur das, was spezifisch für LumiScan Text Reader ist; seine eigenen Knoten sind in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/datalayer-reference.html) aufgelistet.

> [!NOTE]
> Ist die Kennzeichnung ein **Code** und kein Text - Data Matrix, QR, Aztec oder ein Barcode -, verwenden Sie die Schwester-App für diesen Code. Ein Code trägt seine eigene Fehlerkorrektur: Er wird entweder exakt dekodiert oder schlägt fehl; ihn als Text zu lesen ist langsamer und weniger zuverlässig.

## Text ist kein Code, und das ändert die Nutzung

Das ist das Wichtigste, was Sie verstehen sollten, bevor Sie die Anwendung in die Produktion nehmen.

Ein Code Reader liefert einen dekodierten Wert oder nichts. Ein OCR-Leser liefert immer **etwas**, und eine Fehllesung sieht genauso aus wie ein korrektes Leseergebnis:

- jedes Wort kommt mit einer **Konfidenz** zurück, nicht mit einer Garantie;
- ein unbekanntes Zeichen wird **ersetzt** statt abgelehnt - `O` statt `0`, `S` statt `5`;
- dasselbe Etikett wird unterschiedlich gelesen, je nachdem, wie es zugeschnitten wurde und welche Zeichen erlaubt waren.

Die Anwendung ist darauf ausgelegt. Zwei Einstellungen machen aus einem plausiblen Leseergebnis ein vertrauenswürdiges, und beide stehen standardmäßig auf dem freizügigen Wert, damit eine frische Installation Ihnen zeigt, was sie tatsächlich sehen kann:

| Einstellung | Wirkung |
| --- | --- |
| `input/characters/mode` | Schränkt ein, welche Zeichen zurückgegeben werden dürfen. Eine Teilenummer, die immer nur aus Ziffern besteht, kann mit `DIGITS` gelesen nicht mit einem `O` zurückkommen. Das beseitigt eine ganze Klasse von Fehlern, statt sie nachträglich zu filtern. |
| `input/min-score` | Die Konfidenz, die ein Wort erreichen muss, um gemeldet zu werden. Beim Standardwert `0` wird alles gemeldet, auch Vermutungen, denen die Engine kaum traut. |

Setzen Sie beide, bevor Sie sich auf ein Leseergebnis verlassen. Siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html).

## Was ein Leseergebnis enthält

`output/result` enthält den gesamten Text, so wie die Engine ihn angeordnet hat, **und** eine Liste pro Wort mit einer Konfidenz und einer Position für jedes Wort. Sie beantworten unterschiedliche Fragen:

- lesen Sie den gesamten Text, wenn die **Form** zählt - eine mehrzeilige Adresse, ein Etikett mit Kopfzeile;
- lesen Sie die Wortliste, wenn der **Inhalt** zählt und eine falsche Antwort schlimmer ist als keine.

Ebenfalls im Ergebnis: Sprache, Engine und Layout, die **tatsächlich** verwendet wurden. Der letzte Punkt ist wichtig, weil eine Sprache, deren Modell nicht installiert ist, stillschweigend durch Englisch ersetzt und nicht abgelehnt wird - siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).

## Ein leeres Leseergebnis ist kein Fehler

Ein Durchlauf, der nichts findet, meldet Erfolg mit null Wörtern. Das ist die normale Antwort für einen leeren Träger, ein falsch herum liegendes Teil oder ein Etikett außerhalb des Bildes.

Entscheiden Sie anhand der Wortanzahl, nicht anhand des Statuscodes, ob ein Teil Text trug. Jeder Grund, aus dem ein Durchlauf wirklich fehlschlagen kann - eine Kamera, die nicht antwortet, eine unbrauchbare Einstellung, eine Engine, die nicht starten konnte -, wird stattdessen als negativer Statuscode gemeldet.

> [!IMPORTANT]
> In einem Fall wird ein Leseergebnis leer, obwohl der Text einwandfrei lesbar ist: ein Farbbild, in dem ein Foto oder eine andere farbenfrohe Szene mit im Bild ist. Ist ein Leseergebnis leer und Sie können den Text im Bild sehen, setzen Sie `input/preprocess = GRAYSCALE`, bevor Sie etwas anderes untersuchen - siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html).

# Voraussetzungen – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html

## Lizenz {#licence}

Wie LumiScan Text Reader lizenziert wird, hängt davon ab, wo Sie es gekauft haben und wo es läuft:

| Gekauft bei | Läuft auf | Lizenzierung |
| --- | --- | --- |
| HD Vision Systems | Windows 11 oder Ubuntu 24.04 | Die Lizenz liegt auf Ihrem LumiScan Key. Sie ist ein Einmalkauf und wird nicht verlängert.<br><br>[Lizenzierungsweg: gekauft bei HD Vision Systems](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-hdvs.html) |
| ctrlX Store | Windows 11 | Die Lizenz liegt in ctrlX WORKS. Zusätzlich ist der LumiScan Key erforderlich; er schützt die Software vor Reverse Engineering.<br><br>[Lizenzierungsweg: ctrlX Store, Windows](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-ctrlx-windows.html) |
| ctrlX Store | ctrlX OS (ctrlX CORE oder IPC) | ctrlX-Lizenz `SWL-W-XCx-TEXTxxRDSxHDVSx-V1NN`, eine Lizenz pro zehn Module.<br><br>[Lizenzierungsweg: ctrlX Store, ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-ctrlx-os.html) |

Jedes Gerät, auf dem LumiScan Text Reader gleichzeitig läuft, benötigt einen eigenen LumiScan Key. Keys können zwischen Geräten ausgetauscht werden.

Wie Sie die CodeMeter Runtime installieren und Lizenzen anfordern, verlängern und an einem anderen PC verwenden, steht in [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund wird in das Systemprotokoll geschrieben.

## Eine Plattform und ihr Data Layer

| Plattform | Data Layer |
| --- | --- |
| ctrlX OS (ctrlX CORE oder ctrlX IPC) | ctrlX Data Layer, bereitgestellt von ctrlX OS |
| ein PC mit Windows 11 oder Ubuntu 24.04 | LumiScan Keryx, der Data Layer von HD Vision Systems für PCs |

Auf ctrlX OS ist für den Data Layer nichts zu installieren.

Auf einem PC startet die Anwendung den LumiScan-Keryx-Broker, wenn keiner läuft; Installation und Einrichtung von LumiScan Keryx sind in [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html) beschrieben.

## Eine Bildquelle auf demselben Gerät

Die Anwendung liest ihre Bilder vom Data-Layer-Bildknoten einer anderen Anwendung. Diese Anwendung muss auf **demselben Gerät** laufen wie der Text Reader - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC. Ein entfernter Data-Layer-Zugriff wird nicht unterstützt.

In der Praxis ist das LumiScan Cam Driver, aber jede Anwendung funktioniert, solange ihr Bildknoten diese vier Kindknoten bereitstellt:

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `data` | Array aus uint8 | Rohe, unkomprimierte Pixeldaten |
| `width` | uint64 | Bildbreite in Pixeln |
| `height` | uint64 | Bildhöhe in Pixeln |
| `pixel-type` | string | Name des GenICam-Pixelformats |

### Unterstützte Pixelformate

`Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8`, `BayerRG12`.

Bayer-Bilder werden vor dem Lesen in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert.

Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.

## Sprachmodelle

Die Anwendung wird mit installiertem Englisch (`eng`) und dem Orientierungsmodell (`osd`) ausgeliefert; das reicht, um Text in lateinischer Schrift ohne weitere Einrichtung zu lesen.

Andere Sprachen benötigen ihre Tesseract-Datei `.traineddata` in einem Verzeichnis, das die Anwendung lesen kann - auf ctrlX OS funktioniert dank der Schnittstelle `removable-media` ein USB-Stick -, und `system/set-tessdata-dir` muss darauf zeigen. Siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).

## Bildqualität

OCR stellt höhere Anforderungen an das Bild als das Lesen von Codes, und keine Einstellung holt Text zurück, den die Kamera nicht erfasst hat. Als Faustregel:

- Zeichen mindestens **20 Pixel hoch**, bei kleinem oder verrauschtem Druck 30 oder mehr;
- guter Kontrast zwischen Kennzeichnung und Hintergrund;
- der Text im Fokus und nicht von der Beleuchtung überstrahlt;
- der Text ungefähr aufrecht, sofern Sie kein Layout mit Orientierungserkennung aktivieren.

Nadeldruck- und lasergravierte Kennzeichnungen sind schwieriger als gedruckter Text. Hat `engine = DEFAULT` damit Probleme, lohnt sich `LEGACY` als erster Versuch.

## Speicher

Die Anwendung speichert nichts außer ihrer Modulliste und deren Einstellungen - einige Kilobyte JSON im Konfigurationsverzeichnis der Anwendung. Auf ctrlX OS ist dieses Verzeichnis Teil der aktiven Solution. Die Sprachmodelle werden mit der Anwendung installiert und nicht beschrieben. Wo das Verzeichnis auf jeder Plattform liegt, steht in [In der Einstellungsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#saving).

Der Bild-Stream (experimentell) fügt daneben einen Ordner hinzu, `settings-history/`: eine kleine JSON-Datei für jeden Einstellungs-Hash, den ein Modul veröffentlicht, nie gelöscht. Siehe [Einen Bild-Stream verarbeiten](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html).

## Zeitverhalten

Das Lesen ist **synchron**: Der Aufruf von `execute` kehrt zurück, wenn das Lesen abgeschlossen ist.

Wie lange das dauert, hängt vor allem davon ab, wie viel Bild die Engine erhält. Deshalb ist `input/crop` die erste Einstellung, zu der Sie greifen sollten, wenn ein Zyklus zu langsam ist - ein enger Ausschnitt um das Etikett ist schneller und genauer als das ganze Bild. Die Layouts `AUTO_OSD` und `SPARSE_OSD` kosten deutlich mehr als die anderen, weil sie ein zweites Modell laden und vor dem Lesen die Orientierung bestimmen.

Siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html).

# Eine Methode ausführen – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execute-a-method.html

Jede Operation dieser Anwendung - Text lesen, die Sprachmodelle wählen und die Modulverwaltung - wird auf dieselbe Weise gestartet und meldet ihren Ausgang auf dieselbe Weise. Es sind Execute-Methoden des Data Layer; wie Execute-Methoden allgemein funktionieren, ist in [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html) beschrieben.

## Der Aufbau einer Operation

Eine Operation liegt unter ihrer eigenen Adresse und hat immer drei Teile:

```
<operation>/execute                 write here to run it
<operation>/input/...               the values it works on
<operation>/output/status-code      what happened, as a number
<operation>/output/status-text      what happened, in words
```

Manche Operationen haben mehr unter `output/` - zum Beispiel den Text eines Leseergebnisses -, aber `execute`, `status-code` und `status-text` sind immer vorhanden.

## Eine Operation ausführen

1. Schreiben Sie die Eingabeknoten.
2. Schreiben Sie auf `execute`. Der Wert spielt keine Rolle; der Schreibvorgang selbst löst die Operation aus.
3. Lesen Sie `output/status-code`, um zu erfahren, ob sie funktioniert hat.

Das Schreiben auf `execute` ist ein **blockierender Aufruf**: Er kehrt zurück, wenn die Operation abgeschlossen ist. Sie müssen also kein "ready"-Flag pollen und keinen Zustand in Ihrem Programm verfolgen. Eingaben behalten ihre Werte zwischen den Durchläufen, eine wiederholte Operation braucht also nur Schritt 2.

## Den Ausgang prüfen

`output/status-code` ist eine vorzeichenbehaftete Zahl, und **allein das Vorzeichen sagt Ihnen, ob es funktioniert hat**:

| Wert | Bedeutung |
| --- | --- |
| größer als 0 | Die Operation war erfolgreich |
| 0 | Die Operation ist seit dem Start der Anwendung nicht gelaufen |
| kleiner als 0 | Die Operation ist fehlgeschlagen und hat nichts erzeugt |

Die Prüfung in einer SPS ist also einfach `status-code < 0`. Einen bestimmten Code brauchen Sie nur, wenn Sie auf verschiedene Fehler unterschiedlich reagieren wollen - etwa auf eine nicht installierte Sprache anders als auf eine Kamera, die nicht antwortet.

`output/status-text` enthält denselben Ausgang als Satz und nennt den beanstandeten Wert, wenn es einen gibt:

```
ok: 4 word(s), mean score 0.91 (eng, SINGLE_BLOCK)
error: crop/startX + crop/width (100 + 900 = 1000) exceeds the image width 640
```

Lesen Sie ihn, wenn etwas schiefgeht; bauen Sie keine Logik darauf auf, weil sich der Wortlaut zwischen Releases ändern kann. Die vollständige Liste der Codes steht in [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execution-status.html).

> [!NOTE]
> Der Grund kommt auf `output/status-text` an, nicht in der Antwort auf den `execute`-Schreibvorgang selbst. Ein fehlgeschlagener Schreibvorgang antwortet nur mit einem Statuscode - über REST ein bloßes `400`. Der Data Layer verwirft jedes Detail, das ein Provider an einen fehlgeschlagenen Aufruf anhängt; deshalb erfahren Sie, was falsch war, indem Sie anschließend `output/status-text` lesen. Die Ergebnisse, mit denen ein Schreibvorgang antworten kann, und ihre Namen auf dem ctrlX Data Layer und auf LumiScan Keryx sind in [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results) aufgelistet.
>
> Derselbe Text wird in das Anwendungsprotokoll geschrieben, sodass ein Fehler auch ganz ohne den Data Layer diagnostizierbar ist: auf ctrlX OS über das ctrlX Logbook oder `journalctl`, auf einem PC über die Konsolenausgabe der Anwendung. Sind mehrere Eingaben falsch, erhält jede ihre eigene Warnzeile.

## Eine Operation zur Zeit

Ein Modul führt jeweils eine Operation aus. Eine zweite zu starten, während die erste noch läuft, stellt sie nicht in eine Warteschlange - sie kehrt sofort mit Statuscode `-1` (belegt) zurück und tut nichts. Der Schreibvorgang selbst antwortet mit `TooManyOperations` (ctrlX: `DL_TOO_MANY_OPERATIONS`), siehe [Eine Operation zur Zeit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html#busy).

Die Sperre gilt pro Modul, verschiedene Module lesen also parallel - eine zweite Kamera wird von der ersten nicht aufgehalten.

## Die Ausgaben gehören zum startenden Durchlauf

Jede Methode leert ihre eigenen Ausgabeknoten, sobald sie beginnt - `read-text` sein `output/result`. Sie werden geleert, **bevor** irgendetwas fehlschlagen kann; ein Durchlauf, der aus irgendeinem Grund fehlschlägt, lässt sie also leer zurück, statt das Ergebnis eines früheren Durchlaufs zu behalten.

Deshalb ist es sicher, eine Ausgabe zu lesen, ohne vorher `output/status-code` zu prüfen: Was Sie sehen, ist entweder das Ergebnis dieses Durchlaufs oder nichts, nie ein veralteter Wert von einem früheren Bild.

`output/status-code` und `output/status-text` sind die Ausnahme - sie beschreiben immer den letzten Versuch, und genau das ist ihr Zweck.

> [!WARNING]
> **Lesen Sie eine Ausgabe, bevor Sie den nächsten Durchlauf auslösen.** Die Ausgaben beschreiben den jüngsten Durchlauf, und der nächste Aufruf leert sie in dem Moment, in dem er startet. Wenn Sie `execute` erneut aufrufen und dann das vorherige Ergebnis lesen, erhalten Sie nichts.
>
> Der einzige Fall, der **nichts** leert, ist ein Aufruf, der als `-1` (belegt) abgelehnt wird: Er ist nie gelaufen und lässt die Ausgaben der laufenden Operation unberührt. Ein zweites `execute`, das direkt nach dem ersten ausgelöst wird, hat also zwei mögliche Ausgänge, und sie unterscheiden sich:
>
> - der erste Durchlauf **läuft noch** - der zweite wird mit `-1` abgelehnt, und die Ausgaben enthalten noch den Durchlauf davor;
> - der erste Durchlauf ist **gerade fertig** - der zweite wird angenommen und leert die Ausgaben, die der erste gerade erst geschrieben hat.
>
> Warten Sie, bis `execute` zurückkehrt, lesen Sie die Ausgaben und lösen Sie erst dann den nächsten Durchlauf aus.

# Ausführungsstatus – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execution-status.html

Jede Operation meldet ihren Ausgang auf zwei Knoten neben sich: `output/status-code` für Ihr Programm und `output/status-text` für einen Menschen. Diese Codes sind der Ausführungsstatus der Finder, nicht der Modulstatus von Cam Driver, AI Object Matching oder Calibration; siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

## Statuscodes

| Code | Bedeutung | Wann er auftritt |
| --- | --- | --- |
| `0` | Leerlauf | Die Operation ist seit dem Start der Anwendung nicht gelaufen |
| `1` | OK | Die Operation wurde abgeschlossen. Ein Lesevorgang kann trotzdem keine Wörter gefunden haben - das ist ein normales Ergebnis, kein Fehler |
| `-1` | Belegt | Eine andere Operation desselben Moduls lief noch. Es wurde nichts getan; versuchen Sie es erneut, wenn sie abgeschlossen ist |
| `-2` | Ungültige Eingabe | Ein Eingabewert kann nicht verwendet werden - ein erforderlicher Knoten ist leer, ein unbekanntes `input/engine`, `input/layout`, `input/preprocess` oder `input/characters/mode`, ein leerer Zeichensatz, eine Sprache ohne installiertes Modell, ein Ausschnitt, der nicht in das Bild passt, oder eine Bildadresse, die auf diese Anwendung selbst zeigt |
| `-3` | Bild lesen fehlgeschlagen | Der Bildknoten an der angegebenen Adresse fehlt, ist leer, inkonsistent oder verwendet ein nicht unterstütztes Pixelformat. Prüfen Sie, ob die Kameraanwendung läuft und ein Bild aufgenommen hat |
| `-4` | Quelle nicht gefunden | Eine erforderliche Datei oder ein Verzeichnis fehlt oder ist nicht lesbar - bei `system/set-tessdata-dir` ein Pfad, der kein Verzeichnis ist |
| `-5` | Ungültige Ausschnittsregion | Die Region of Interest passt nicht in das Bild. `read-text` meldet einen Ausschnitt, der nicht passt, als `-2`, siehe [Text lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html) |
| `-6` | Schreiben fehlgeschlagen | Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger |
| `-7` | Algorithmus fehlgeschlagen | Die OCR-Engine konnte nicht starten oder ein Sprachmodell konnte nicht geladen werden - zum Beispiel ein Modell, dessen Upload noch läuft |
| `-8` | Veröffentlichen fehlgeschlagen | Das Ergebnis konnte nicht auf den Data Layer zurückgeschrieben werden |
| `-9` | Modul nicht gefunden | Das genannte Modul existiert nicht. Prüfen Sie `system/modules` für die aktuelle Liste |
| `-10` | Modul existiert bereits | Ein Modul mit diesem Namen ist bereits vorhanden |
| `-11` | Lizenz nicht verfügbar | Keine Lizenz deckt das Modul ab. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/module-management.html) |

> [!NOTE]
> Diese Zahlen sind Teil der Schnittstelle der Anwendung. In späteren Releases können neue Codes hinzukommen, aber bestehende ändern nie ihre Bedeutung; Logik, die auf ihnen aufbaut, funktioniert nach einem Update weiter.
>
> Deshalb ist auch die Prüfung des **Vorzeichens** der robustere Test: `status-code < 0` bleibt korrekt, selbst wenn ein Release einen Fehler einführt, den Ihr Programm noch nie gesehen hat.

## Welche Operation welche Codes meldet

| Operation | Mögliche Codes |
| --- | --- |
| `read-text` | `1`, `-1`, `-2`, `-3`, `-7` |
| `system/set-tessdata-dir` | `1`, `-2`, `-4`, `-6` |
| `system/save-module-inputs` | `1`, `-6`, `-9` |

## Statustext

`output/status-text` beginnt immer mit `ok:` oder `error:` und nennt den Grund in Worten. Er wird zur selben Zeit wie der Statuscode geschrieben, sodass beide immer übereinstimmen.

Jede Operation hat ihr eigenes Knotenpaar, und die Knoten behalten ihre Werte, bis diese Operation erneut läuft. Ein fehlgeschlagenes `set-tessdata-dir` stört also nicht das Ergebnis des letzten Lesevorgangs.

# Text lesen – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html

Ein Lesevorgang, auf Anfrage. Nichts geschieht, bis ein Client `<module>/read-text/execute` schreibt.

## Was ein Durchlauf tut

1. Lehnt den Aufruf ab, wenn dieses Modul bereits belegt ist (Statuscode `-1`).
2. **Leert das vorherige Leseergebnis**, damit ein Fehler nie alten Text zurücklässt.
3. Prüft jede Einstellung und meldet **alle** Probleme auf einmal.
4. Liest das Bild von `input/input-image-address`.
5. Wendet `input/crop` an.
6. Führt die OCR-Engine aus und veröffentlicht den Text.

## Die Einstellungen

| Knoten | Standard | Wirkung |
| --- | --- | --- |
| `input/input-image-address` | (leer) | Adresse des zu lesenden Bildknotens, z. B. `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. |
| `input/crop/startX`<br> `input/crop/startY`<br> `input/crop/width`<br> `input/crop/height` | 0 | Der zu lesende Bildausschnitt. Alles null liest das ganze Bild; eine Breite oder Höhe von null reicht bis zum rechten bzw. unteren Rand. **Schneiden Sie eng um den Text zu** - siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html). |
| `input/language` | `eng` | Mit welchem Sprachmodell gelesen wird. Die auf diesem Gerät installierten Modelle sind auf `system/languages` aufgelistet. |
| `input/engine` | `DEFAULT` | `DEFAULT` wählt die beste verfügbare Engine, `LSTM` ist die moderne Engine mit neuronalem Netz, `LEGACY` die ursprüngliche Engine mit Mustervergleich, und `COMBINED` führt beide aus. `LEGACY` lohnt sich als Versuch bei Nadeldruck- und lasergravierten Kennzeichnungen. |
| `input/layout` | `SINGLE_BLOCK` | Wie viel Struktur im Bild gesucht wird. |
| `input/preprocess` | `NONE` | Was mit dem Bild vor dem Lesen geschieht. Greifen Sie zu `GRAYSCALE`, wenn ein Farbbild ganz ohne Wörter zurückkommt; das passiert, wenn ein Foto zusammen mit dem Text im Bild ist - siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html). |
| `input/characters/mode`<br> `input/characters/allow`<br> `input/characters/deny` | `ALL_SYMBOLS`<br> (leer)<br> (leer) | Welche Zeichen zurückgegeben werden dürfen. |
| `input/min-score` | `0` | Die Konfidenz, die ein Wort erreichen muss, um gemeldet zu werden, zwischen 0 und 1. |

## Das Ergebnis lesen

`output/result` ist ein `text_read_result`-Flatbuffer.

| Feld | Bedeutung |
| --- | --- |
| `text` | Das gesamte Leseergebnis genau so, wie die Engine es erzeugt hat, Zeilen durch Zeilenumbrüche getrennt. **Nicht nach `min-score` gefiltert.** |
| `words[].text`<br> `words[].score`<br> `words[].bbox_x` … `bbox_height` | Ein erkanntes Wort, seine Konfidenz von 0 bis 1 und ein Rahmen um das Wort in den Koordinaten der gelesenen Region. |
| `word_count` | Wie viele Wörter gemeldet werden. |
| `mean_score` | Mittlere Konfidenz über die gemeldeten Wörter; 0, wenn es keine gibt. |
| `min_score` | Der angewendete Schwellwert, damit eine kurze Wortliste als "streng" und nicht als "schlechtes Bild" gelesen wird. |
| `language` | Die **tatsächlich** verwendete Sprache - nicht immer die angeforderte. |
| `engine`, `layout` | Wie tatsächlich verwendet. |
| `image_width`, `image_height` | Die gelesene Region - das ganze Bild, sofern kein Ausschnitt gesetzt war. |
| `timestamp` | Mikrosekunden seit der Epoche, wann der Lesevorgang abgeschlossen wurde. |

### `text` und `words[]` dürfen sich unterscheiden, mit Absicht

`text` ist die eigene Ausgabe der Engine, mit den Zeilenumbrüchen, die sie gefunden hat. `words[]` ist nach `min-score` gefiltert. Bei `min-score` auf `0.8` erscheint ein Wort, das die Engine mit `0.4` gemeldet hat, in `text`, aber nicht in `words[]`.

Wenn beide übereinstimmen müssen, lesen Sie `text` nur dann, wenn `word_count` die erwartete Zahl ist.

## Wenn es fehlschlägt

| Situation | Statuscode | Was Sie erhalten |
| --- | --- | --- |
| Eine andere Operation auf diesem Modul läuft | `-1` | Nichts getan; das vorherige Leseergebnis bleibt unberührt |
| Eine Einstellung ist unbrauchbar | `-2` | **Jedes** Problem in einem `status-text` benannt |
| Der Bildknoten kann nicht gelesen werden | `-3` | Leeres Ergebnis |
| Der Ausschnitt passt nicht in das Bild | `-2` | Leeres Ergebnis |
| Die OCR-Engine konnte nicht starten | `-7` | Leeres Ergebnis, mit dem Grund in `status-text` |
| Nichts Lesbares im Bild | `1` (Erfolg) | Leerer Text, `word_count` 0 |

Die letzten beiden Zeilen sind der Unterschied, der in der Produktion am meisten zählt: Ein Leser, der nicht starten konnte, meldet `-7` und nennt den Grund, während ein funktionierender Leser, der auf ein leeres Teil schaut, Erfolg ohne Wörter meldet. Früher waren beide nicht zu unterscheiden.

## Die Ausgaben gehören zum startenden Durchlauf

Jedes `execute` leert `output/result` in dem Moment, in dem es beginnt; ein Client muss ein Ergebnis also lesen, bevor er den nächsten Lesevorgang auslöst. `status-code` und `status-text` sind die Ausnahme - sie beschreiben immer den letzten Versuch.

# Text auf einem Bild-Stream lesen (experimentell) – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html

> [!IMPORTANT]
> Der Bild-Stream ist **experimentell**. Seine Knoten und Einstellungen können sich noch ändern. Verwenden Sie ihn zur Evaluierung und prüfen Sie ihn mit Ihren Kameras und Ihrem Data Layer, bevor Sie sich darauf verlassen.

`read-text` liest ein Bild pro Aufruf: Ihr Programm setzt `input/input-image-address` und schreibt auf `execute`. Ein Bild-Stream funktioniert andersherum. Der Cam Driver veröffentlicht jedes Bild, das er aufnimmt, auf `<camera name>/control/publish/output/stream/frame`, mit seiner Größe, seinem Pixelformat und seiner Lineage (siehe das Handbuch des Cam Driver, *Bilder streamen*). Ein Modul abonniert den Stream einer Kamera, liest jedes Bild, sobald es eintrifft, und veröffentlicht ein Ergebnis pro Bild auf `control/subscribe/output/stream/result`. Der Stream funktioniert auf dem ctrlX Data Layer und auf LumiScan Keryx gleich; das allen LumiScan-Apps gemeinsame Konzept ist in [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) beschrieben. Diese Seite beschreibt, was beim Text Reader besonders ist.

Jedes Bild wird mit den Eingaben von `read-text` gelesen, wie sie in diesem Moment sind: Sprache, Engine, Layout, Zeichensatz, Ausschnittsregion und jeder andere Knoten unter `read-text/input/`. Die einzige Eingabe, die der Stream nicht verwendet, ist `input/input-image-address`: Das Bild tritt an ihre Stelle. Ändern Sie eine Eingabe, während der Stream läuft, wird das nächste Bild mit dem neuen Wert gelesen.

Jedes Ergebnis trägt die Lineage seines Bildes - welche Kamera es aufgenommen hat, in welchem Lauf des Kamera-Streams, als welches Bild des Laufs - ergänzt um den eigenen Schritt des Moduls. Siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#lineage).

Standardmäßig fällt das Modul nie hinter seine Kamera zurück. Treffen Bilder schneller ein, als das Modul sie liest, nimmt es jedes Mal das neueste Bild, sobald das vorherige Lesen abgeschlossen ist. Die Bilder dazwischen werden als übersprungen gezählt. Wie viele Bilder warten dürfen, wird mit der Warteschlangengröße festgelegt, siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#queue-size).

Ein Modul nimmt den Stream einer Kamera. Für eine andere Kamera oder andere Einstellungen verwenden Sie ein anderes Modul.

## Die Knoten des Streams {#addresses}

Jedes Modul hat die Knoten des Streams, ob es einen Stream abonniert oder nicht. Um sie zu verwenden, ist kein Neustart nötig. Alle Adressen unten beginnen mit `hdvisionsystems/lumiscan-text-reader/<module-id>/`. Sie liegen neben `read-text/`, nicht darin.

**Tabelle 1. Methoden**

| Adresse | Bedeutung |
| --- | --- |
| `control/subscribe/execute` | Prüft die fünf Eingaben von `control/subscribe` gemeinsam, speichert sie in der Einstellungsdatei des Moduls und wendet sie dann an: Ein laufender Stream folgt bei seinem nächsten Zyklus, ohne Neustart. Eine Eingabe allein zu schreiben ändert nichts. Siehe [Die Quelle ändern](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die Quelle, die `control/unsubscribe/input/address` nennt, was auch den Stream-Modus beendet. Das Tag bleibt. Wird wie ein Subscribe in der Einstellungsdatei des Moduls gespeichert. |

**Tabelle 2. Eingaben von control/subscribe**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/input/enable` | bool | Stream-Modus: `true` lässt den Stream laufen, `false` stoppt ihn. |
| `control/subscribe/input/address` | string | Die eine Quelle: der Stream-Ordner einer Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Das Modul liest dessen Knoten `frame`. Eine andere Adresse ersetzt die Quelle. |
| `control/subscribe/input/tag` | string | Das Tag, das das Modul auf seine Ergebnisse setzt: Der Schritt des Moduls in der Lineage jedes Ergebnisses trägt es, sodass jeder, der ein Ergebnis weiter unten liest, sieht, welches Modul es erzeugt hat. Leer: die Modul-ID, das letzte Segment der Moduladresse, zum Beispiel `module-1`. Ein neues Tag markiert das nächste Ergebnis; die Quelle bleibt abonniert. |
| `control/subscribe/input/queue-size` | uint32 | Wie viele Bilder warten dürfen, während ein Bild gelesen wird: `1` bis `64`. Siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#queue-size). |
| `control/subscribe/input/keep-latest-output` | bool | `true`, um jedes Stream-Ergebnis zusätzlich nach `read-text/output/result` zu schreiben. Siehe [Die neueste Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#keep-latest-output). |

Die Eingaben beginnen mit dem, was beim Start der Anwendung angewendet ist; ein Client kann also eine davon ändern und ausführen.

Was die Quelle enthalten muss: Lesen Sie `hdvisionsystems/lumiscan-text-reader/system/meta/subscription-schema`, für jedes Modul dasselbe. Es ist ein JSON Schema des Knotens `frame` der Quelle, ein `stream_image` mit seiner `lineage` und seinem `image`, in seiner JSON-Form. Siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/datalayer-reference.html).

**Tabelle 3. Eingabe von control/unsubscribe**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/unsubscribe/input/address` | string | Die zu entfernende Quelle: die Adresse, die `setting/stream/address` zeigt. Ein `/` an einem der beiden Enden zählt nicht. |

**Tabelle 4. Einstellungen**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `setting/stream/enable`, `setting/stream/address`, `setting/stream/tag`, `setting/stream/queue-size`, `setting/stream/keep-latest-output` | wie die Eingaben | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat, so wie die Einstellungsdatei es enthält. Schreibgeschützt. |
| `setting/settings-hash` | string | Der Hash dessen, womit die Ergebnisse erzeugt werden, als 16 Hex-Ziffern. Schreibgeschützt. Siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#settings-hash). |

**Tabelle 5. Ausgaben**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/output/stream/active` | bool | `true`, solange der Stream läuft. |
| `control/subscribe/output/stream/result` | flatbuffers `stream_texts` | Der aus jedem Bild gelesene Text und die Lineage des Bildes. Abonnieren Sie ihn, um jedes Ergebnis zu erhalten. Siehe [Das Ergebnis eines Bildes](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#result). |
| `control/subscribe/output/stream/last-failure` | string | Warum das letzte Bild, das nicht gelesen werden konnte, fehlgeschlagen ist. Es nennt die Quelle über ihre Adresse, siehe [Das Ergebnis eines Bildes](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#result). Wird beim Start des Streams geleert. |
| `control/subscribe/output/stream/statistics/…` | uint64 | Zähler des aktuellen oder des letzten Streams, siehe [Die Statistik lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#statistics). |

Der Stream veröffentlicht seine Ergebnisse auf `control/subscribe/output/stream/result`. Von den Knoten von `read-text` schreibt er nur `read-text/output/result`, und nur mit eingeschaltetem `keep-latest-output`: `status-code` und `status-text` behalten, was der letzte Aufruf der Methode dort hinterlassen hat.

## Einrichten {#setting-up}

1. Stellen Sie sicher, dass der Stream des Cam Driver läuft: sein `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active` ist `true`.
2. Setzen Sie die Eingaben von `read-text` wie für einen einzelnen Lesevorgang, siehe [Text lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html). Ein Aufruf von `read-text/execute` auf dem `output/image` der Kamera ist ein schneller Weg, sie zu prüfen.
3. Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, nach `control/subscribe/input/address`. Lassen Sie `control/subscribe/input/tag` leer, um die Ergebnisse mit der Modul-ID zu markieren, oder schreiben Sie ein eigenes Tag hinein.
4. Abonnieren Sie `control/subscribe/output/stream/result`.
5. Setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie dann auf `control/subscribe/execute`. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist. Ab dann treffen die Ergebnisse ein.
6. Zum Stoppen setzen Sie `control/subscribe/input/enable` auf `false` und schreiben erneut auf `control/subscribe/execute`. Das gerade gelesene Bild wird zuerst fertig gelesen.

Auf ctrlX OS verwenden Sie für diese Schritte die Data-Layer-Ansicht der ctrlX-OS-Weboberfläche oder Ihr SPS-Programm.

Auf einem PC dieselben Schritte mit `krxclient`, dem Kommandozeilen-Client von LumiScan Keryx, der eine SPS vertritt (siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#krxclient)). Ergänzen Sie die Optionen `--keryx-backend` und `--keryx-url`, die Ihr Broker benötigt:

```none
krxclient write hdvisionsystems/lumiscan-text-reader/module-1/control/subscribe/input/address hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream
krxclient write hdvisionsystems/lumiscan-text-reader/module-1/control/subscribe/input/enable true
krxclient execute hdvisionsystems/lumiscan-text-reader/module-1/control/subscribe/execute
krxclient subscribe hdvisionsystems/lumiscan-text-reader/module-1/control/subscribe/output/stream/result --count 5
```

`krxclient subscribe` zeigt einen Flatbuffer nur über seine Größe an. Es sagt Ihnen, dass Ergebnisse eintreffen, nicht, was sie enthalten.

Gut zu wissen:

- Der Stream-Modus ist ein **Pegel**, kein Befehl: Der Stream läuft, solange das angewendete `enable` `true` ist.
- Der Stream kann vor dem Stream des Cam Driver gestartet werden. Ergebnisse treffen ein, sobald Bilder eintreffen.
- Was `control/subscribe/execute` anwendet, wird in der Einstellungsdatei des Moduls gespeichert. Nach einem Neustart der Anwendung startet das Modul, wie es war: Eines, das gestreamt hat, streamt sofort wieder, ohne dass Ihr Programm etwas ausführt. Siehe [In der Einstellungsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#saving).

## Die Quelle ändern {#subscribing}

Ein Modul nimmt eine Quelle. Eine SPS oder ein anderer Client ändert sie, während die Anwendung läuft, mit oder ohne laufenden Stream:

1. Schreiben Sie die neuen Werte auf die Eingaben von `control/subscribe` - nur die, die Sie ändern: Die anderen enthalten, was angewendet ist.
2. Schreiben Sie auf `control/subscribe/execute`. Die Eingaben werden gemeinsam geprüft, in der Einstellungsdatei des Moduls gespeichert und erst dann angewendet: `setting/stream/` zeigt sie sofort, und ein laufender Stream folgt bei seinem nächsten Zyklus. Eine andere Adresse ersetzt die Quelle; die Bilder, die bei der alten warteten, werden als übersprungen gezählt. Ein neues Tag, eine neue Warteschlangengröße oder ein neues `keep-latest-output` braucht kein neues Abonnement: Ein neues Tag markiert das nächste Ergebnis.
3. Um die Quelle zu entfernen, schreiben Sie ihre Adresse nach `control/unsubscribe/input/address` und dann auf `control/unsubscribe/execute`. Der Stream-Modus endet damit. Die Eingaben von `control/subscribe` werden auf das gesetzt, was angewendet wurde: Stream-Modus aus, keine Adresse. Das Tag bleibt: Es markiert die Ergebnisse des Moduls, nicht die Quelle.

Kann die Einstellungsdatei nicht geschrieben werden, ändert sich nichts. Siehe [In der Einstellungsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#saving).

Die Methoden antworten mit einem Ergebnis des Data Layer. Sein Name unterscheidet sich zwischen den beiden Data Layern, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results):

| ctrlX OS | PC (LumiScan Keryx) | Wann |
| --- | --- | --- |
| `DL_OK` | `Ok` | Erledigt. |
| `DL_INVALID_VALUE` | `Rejected` | `control/subscribe/execute`: Stream-Modus ohne Adresse oder eine Warteschlangengröße außerhalb von `1` bis `64`. `control/unsubscribe/execute`: Die Adresse ist nicht die Quelle, oder es gibt keine Quelle. |
| `DL_CREATION_FAILED` | `CreationFailed` | Die Einstellungsdatei konnte nicht geschrieben werden, zum Beispiel weil sie kein gültiges JSON ist. Nichts hat sich geändert. |

Diese Methoden haben keinen `status-text`. Der Grund für eine Ablehnung wird in das Anwendungsprotokoll geschrieben.

Kann die Quelle nicht abonniert werden, versucht das Modul es alle 5 Sekunden erneut, solange der Stream läuft, und protokolliert den ersten Fehlschlag.

## Das Ergebnis eines Bildes {#result}

`control/subscribe/output/stream/result` enthält eine FlatBuffers-Tabelle vom Typ `stream_texts` (Datei-Identifier `HSTX`), auf dem Data Layer registriert als `types/hdvisionsystems/lumiscan-text-reader/stream_texts`. Ihr kompiliertes Schema ist als `bfbs/stream_texts.bfbs` installiert.

| Feld | Bedeutung |
| --- | --- |
| `lineage` | Woher das Ergebnis stammt, siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#lineage). |
| `result` | Das Leseergebnis, als `hdv.text_read.Result`: dieselbe Tabelle, die `read-text` für dasselbe Bild nach `output/result` schreibt, beschrieben in [Text lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html). |

Ein Lesen von `control/subscribe/output/stream/result` liefert das neueste Ergebnis; vor dem ersten Bild ein leeres. Das letzte Ergebnis bleibt nach dem Stopp des Streams erhalten.

Ein Bild wird dekodiert, wie `read-text` den Bildknoten dekodiert, es werden also dieselben Pixelformate akzeptiert, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html). Ein Bild aus dem Stream und dasselbe Bild über `input/input-image-address` gelesen ergeben dasselbe Leseergebnis.

Ein Bild, das nicht gelesen werden kann, ergibt kein Ergebnis. Es wird in `statistics/failed-frames` gezählt, und `control/subscribe/output/stream/last-failure` nennt den Grund. Die Gründe sind die, die `read-text` in seinem `status-text` nennt: eine Eingabe, die es ablehnen würde - darunter eine Sprache ohne Modell -, eine Ausschnittsregion, die nicht in das Bild passt, eine Region, die nicht gelesen werden kann, eine fehlgeschlagene Erkennung.

### Ein in einer anderen Sprache gelesenes Bild wird verworfen {#language}

`read-text` prüft die Sprache, bevor es liest. Verschwindet das Modell zwischen dieser Prüfung und dem Lesen, liest die Engine stattdessen mit `eng`: `read-text` veröffentlicht das Leseergebnis dann mit einem `NOTE` in seinem `status-text` (siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html)).

Der Stream veröffentlicht ein solches Leseergebnis nicht. Sein Einstellungs-Hash nennt das angeforderte Modell, nicht das verwendete, deshalb schlägt das Bild stattdessen fehl:

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: language 'deu' is no longer installed; the frame was read with 'eng' instead and its result dropped
```

Ein hochgeladenes Modell wird ab dem nächsten Bild verwendet, wie bei `read-text` - ein neues ebenso wie eines, das an Ort und Stelle unter demselben Namen überschrieben wurde: Das Bild wird mit dem Modell gelesen, wie es auf dem Datenträger liegt, und der Hash nennt dieses Modell.

## Die Lineage eines Ergebnisses {#lineage}

`lineage.steps` listet auf, woher das Ergebnis stammt, Ursprung zuerst:

1. Der Schritt der Kamera, wie der Cam Driver ihn erzeugt hat: `producer` ist die Adresse der Kamera, `hdvisionsystems/lumiscan-cam-driver/<camera name>`; `run`, wann der Stream der Kamera gestartet wurde; `sequence` die Nummer des Bildes in diesem Lauf; `external_id` die eigene Bildnummer der Kamera; `settings_hash` die Einstellungen der Kamera; `tag` das Tag des Cam Driver für die Kamera, standardmäßig ihre Modul-ID, zum Beispiel `camera1`.
2. Der Schritt des Moduls: `producer` ist die Adresse des Moduls, `hdvisionsystems/lumiscan-text-reader/<module-id>`; `run`, wann der Stream des Moduls gestartet wurde (jeder Start ist ein neuer Lauf); `sequence` die Nummer des Ergebnisses im Lauf, ab `1`; `settings_hash` die Einstellungen des Moduls, siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Bildes am Modul bis zu seinem Ergebnis, Wartezeit eingeschlossen; `time_us`, wann das Ergebnis erzeugt wurde, in Mikrosekunden seit der Epoche; `tag` das Tag des Moduls, `control/subscribe/input/tag`, oder die Modul-ID, wenn es leer ist.

Ein Ergebnis benennt sein Bild also exakt: die Kamera über `producer`, das Bild über `run` und `sequence`. Um zu wissen, von welcher Kamera ein Ergebnis stammt, lesen Sie den `producer` seines ersten Schritts. Eine Lücke in der `sequence` des Kamera-Schritts zwischen zwei Ergebnissen derselben Kamera sind Bilder, die übersprungen wurden, fehlgeschlagen oder verloren gegangen sind.

Eine Lineage enthält höchstens 16 Schritte. Eine längere behält den Ursprung und die neuesten Schritte, und `dropped` zählt die ausgelassenen Schritte.

Ein Bild ohne Lineage ergibt ein Ergebnis mit dem Schritt des Moduls allein. Ein Wert auf dem Knoten `frame` eines Streams, der kein `stream_image` ist, wird ignoriert und einmal protokolliert.

## Der Einstellungs-Hash {#settings-hash}

`setting/settings-hash` und der `settings_hash` des Modul-Schritts in jedem Ergebnis identifizieren, womit die Ergebnisse erzeugt werden. Der Knoten zeigt den Hash als 16 Hex-Ziffern; der Schritt enthält denselben Wert als Zahl. Der Hash umfasst:

- jede Eingabe von `read-text`, die das Lesen verwendet, genau so, wie sie für das Bild gelesen wurde - alle außer `input/input-image-address`;
- das Sprachmodell, `<language>.traineddata`, über seinen Inhalt: Ein neues Modell, das unter dem alten Namen hochgeladen wird, ist ein neuer Hash. Bei den Layouts `AUTO_OSD` und `SPARSE_OSD` auch das Orientierungsmodell `osd.traineddata` daneben. Die Modelle werden nur gehasht, wenn die Eingaben die Prüfung bestehen;
- Name und Version der Anwendung.

Er umfasst nicht den Stream-Modus, die Quelle, die Warteschlangengröße oder keep-latest-output: Sie wählen und takten die Bilder, sie ändern nicht, was aus ihnen gelesen wird.

`setting/settings-hash` wird etwa jede halbe Sekunde aktualisiert, auch während der Stream aus ist. Wenn ein Hash zum ersten Mal erscheint, schreibt das Modul die Einstellungen, für die er steht, nach `settings-history/<module-id>-<hash>.json` im Konfigurationsverzeichnis der Anwendung, sodass ein in einem Ergebnis gefundener Hash später nachgeschlagen werden kann. Die Anwendung löscht diese Dateien nicht. Eine Datei sieht so aus, gekürzt:

```json
{
    "format": 1,
    "settings": {
        "read-text/input/language": "eng",
        "read-text/input/layout": "SINGLE_BLOCK",
        "read-text/language-model": {
            "file": "<model directory>/eng.traineddata",
            "fnv1a64": "<16 hex digits>"
        },
        "software.name": "lumiscan-text-reader",
        "software.version": "<version>"
    },
    "settingsHash": "<16 hex digits>"
}
```

> [!NOTE]
> Ein Ergebnis trägt nur den Hash. Ein anderer Hash sagt, dass sich etwas geändert hat, womit die Ergebnisse erzeugt werden, nicht was. Um das herauszufinden, vergleichen Sie die beiden Dateien in `settings-history`, die die Hashes nennen, von Hand. Jede Eingabe, die das Lesen verwendet, wird gehasht; eine Änderung, die ein Ergebnis nicht verändert, kann den Hash also trotzdem ändern.

## Die Statistik lesen {#statistics}

Die Zähler beginnen bei jedem Start des Streams bei null, werden etwa viermal pro Sekunde aktualisiert, solange er läuft, und behalten nach dem Stopp ihre letzten Werte. Alle Adressen beginnen mit `control/subscribe/output/stream/statistics/`.

| Zähler | Bedeutung |
| --- | --- |
| `elapsed-ms` | Millisekunden seit dem Start des Streams. Teilen Sie einen Zähler dadurch, um eine Rate zu erhalten. |
| `received-frames` | Bilder, die das Abonnement geliefert hat. |
| `processed-frames` | Gelesene Bilder, jedes mit einem auf `control/subscribe/output/stream/result` veröffentlichten Ergebnis. |
| `skipped-frames` | Nie gelesene Bilder: von neueren aus der Warteschlange verdrängt, während ein Bild gelesen wurde (siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#queue-size)), oder wartend, als die Quelle ersetzt oder entfernt wurde. |
| `failed-frames` | Bilder, die nicht gelesen werden konnten. `control/subscribe/output/stream/last-failure` nennt den Grund für das letzte, und das Protokoll nennt die Fehlschläge, höchstens eine Zeile alle 5 Sekunden. |
| `lost-frames` | Bilder, die verloren gingen, bevor sie eintrafen, ermittelt aus Lücken in der `sequence` der Kamera innerhalb eines Laufs ihres Streams. Eine neue Quelle oder ein neuer Lauf des Kamera-Streams beginnt die Zählung neu. |
| `processing-us` | Mikrosekunden, die alle Lesevorgänge zusammen gedauert haben, ohne die Zeit, die ein Bild auf `read-text` gewartet hat. Teilen Sie durch `processed-frames` für den Mittelwert. |

Bilder, die beim Stopp des Streams noch warten, werden verworfen, ohne gezählt zu werden.

## In der Einstellungsdatei gespeichert {#saving}

Stream-Modus und Quelle sind Einstellungen des Moduls. Sie werden im Member `stream` der Einstellungsdatei des Moduls gespeichert, `<module-id>.json` im Konfigurationsverzeichnis der Anwendung - der Datei, in die `system/save-module-inputs` die Eingaben schreibt.

`control/subscribe/execute` und `control/unsubscribe/execute` speichern dort selbst, was sie anwenden, alle fünf Werte in einem Schreibvorgang, bevor sie sie anwenden. Kann die Datei nicht geschrieben werden, antwortet die Methode mit `DL_CREATION_FAILED` (auf einem PC `CreationFailed`), und nichts ändert sich. Nach einem Neustart abonniert das Modul dieselbe Quelle und startet, wenn `stream.enable` `true` ist, seinen Stream sofort: Niemand muss etwas ausführen.

Das Speichern ändert nur den Member `stream`; der Rest der Datei bleibt, wie er war. Das Modul legt die Datei an, wenn es noch keine gibt - ein Modul, dessen Eingaben nie gespeichert wurden, hat keine. `system/save-module-inputs` wiederum behält den Member `stream`, wenn es die Datei neu schreibt; die Eingaben von `control/subscribe` werden nicht als Eingaben des Moduls gespeichert.

Das Konfigurationsverzeichnis ist:

| Plattform | Konfigurationsverzeichnis |
| --- | --- |
| ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-text-reader` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-text-reader`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader` |

Der Member `stream`, neben den Eingaben von `read-text` (hier gekürzt):

```json
{
    "read-text": {
        "language": "eng"
    },
    "stream": {
        "enable": true,
        "address": "hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream",
        "queueSize": 1,
        "keepLatestOutput": false
    }
}
```

| Schlüssel | Erforderlich | Bedeutung |
| --- | --- | --- |
| `enable` | Nein | Stream-Modus: `true` startet den Stream beim Start der Anwendung. Benötigt eine `address`. `false`, wenn weggelassen. |
| `address` | Nein | Die eine Quelle: der Stream-Ordner einer Kamera. |
| `tag` | Nein | Was die Ergebnisse des Moduls markiert: das `tag` des Modul-Schritts in ihrer Lineage. Die Modul-ID, wenn weggelassen. |
| `queueSize` | Nein | Wie viele Bilder warten dürfen: `1` bis `64`, `1`, wenn weggelassen. |
| `keepLatestOutput` | Nein | `true`, um jedes Stream-Ergebnis zusätzlich nach `read-text/output/result` zu schreiben. `false`, wenn weggelassen. |
| `onEntry` | Nein | Die Schritte, die auf jedes eintreffende Bild angewendet werden, jeder ein Objekt mit einem `kind`, wie das `stream` jeder LumiScan-Anwendung sie hat. Diese Anwendung hat noch keine: Lassen Sie es weg oder leer (`[]`). Ein Schritt startet das Modul außerhalb des Stream-Modus, mit einer Warnung im Protokoll; das Speichern behält ihn. |

`control/subscribe/execute` und `control/unsubscribe/execute` schreiben alle fünf.

Gut zu wissen:

- Die Datei wird einmal gelesen, wenn das Modul beim Start der Anwendung wiederhergestellt wird: ein Modul in der gespeicherten Modulliste oder `module-1` bei einer frischen Installation. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.
- Ein mit `system/create-module` angelegtes Modul startet mit ausgeschaltetem Stream, ohne Quelle, mit einer Warteschlangengröße von `1` und ausgeschaltetem `keep-latest-output`, was immer eine Datei seines Namens enthält. Was es von da an anwendet, wird in diese Datei gespeichert.
- Um ein Modul und seinen Stream nach einem Neustart zurückzubekommen, speichern Sie auch die Modulliste, mit `system/save-current-modules`. Das Speichern einer Liste, die ein Modul nicht mehr nennt, löscht die Datei dieses Moduls und mit ihr seine Stream-Einstellungen. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/module-management.html).
- Ein Wert, der nicht verwendet werden kann, wird ignoriert und protokolliert: ein `enable` oder `keepLatestOutput`, das nicht `true` oder `false` ist, eine `address` oder ein `tag`, das kein String ist, eine `queueSize` außerhalb von `1` bis `64` (`1` wird verwendet). Stream-Modus ohne `address` wird ignoriert: Das Modul startet außerhalb des Stream-Modus.
- Der Member `subscriptions` früherer Versionen wird nicht mehr gelesen, und das Modul protokolliert, dass er umgezogen ist: Geben Sie die Quelle als `address` an.

> [!WARNING]
> Fügen Sie `<module-id>.json` keine Kommentare hinzu. Der Stream liest eine Datei mit Kommentaren, aber die Eingaben des Moduls werden dann beim Start nicht wiederhergestellt: Das Protokoll meldet die Datei als nicht lesbar.

## Die Warteschlangengröße {#queue-size}

`control/subscribe/input/queue-size` legt fest, wie viele Bilder warten dürfen, während ein Bild gelesen wird: `1` bis `64`, standardmäßig `1`. Sie wird als `stream.queueSize` gespeichert, und `setting/stream/queue-size` zeigt den verwendeten Wert. Ein Bild, das eintrifft, wenn so viele warten, verdrängt das älteste von ihnen, was in `statistics/skipped-frames` gezählt wird. Eine neue Warteschlangengröße gilt ab dem nächsten eintreffenden Bild, ohne neues Abonnement.

| Warteschlangengröße | Wirkung |
| --- | --- |
| 1 (Standard) | Das Modul liest das neueste Bild. Es fällt nie zurück; ist das Lesen langsamer als die Kamera, überspringt es Bilder. |
| Mehr als 1 | Kurze Bildschübe werden alle gelesen, und weniger werden übersprungen. Ist das Lesen länger langsamer als die Kamera, fällt das Modul zurück: Es liest Bilder, die bis zu so viele Lesevorgänge alt sind. Jedes wartende Bild hält ein ganzes Bild im Speicher. |

## Die neueste Ausgabe behalten {#keep-latest-output}

Mit `control/subscribe/input/keep-latest-output` `true` - angewendet durch `control/subscribe/execute`, gespeichert als `stream.keepLatestOutput` - schreibt das Modul jedes Stream-Ergebnis zusätzlich nach `read-text/output/result`, so wie `read-text/execute` es schreibt, sobald das Ergebnis auf `control/subscribe/output/stream/result` veröffentlicht ist. Ein Client, der `read-text/output/result` liest, hat dann das Ergebnis des neuesten Bildes, ohne den Stream zu abonnieren. `status-code` und `status-text` werden nicht geschrieben: Sie behalten, was der letzte Aufruf von `read-text` dort hinterlassen hat. Es kostet eine Kopie jedes Ergebnisses. Standardmäßig aus.

## read-text, während der Stream läuft {#while-streaming}

Der Stream und `read-text` verwenden dieselben Eingaben und die eine Erkennungs-Engine des Moduls, und sie laufen auf einem Modul nie gleichzeitig:

- Ein Bild, das eintrifft, während `read-text` läuft, wartet, bis die Methode abgeschlossen ist. Es wird verzögert, nicht fehlgeschlagen.
- Ein Aufruf von `read-text/execute`, während ein Bild gelesen wird, antwortet mit belegt: `output/status-code` ist `-1`, der Schreibvorgang antwortet mit `DL_TOO_MANY_OPERATIONS` (auf einem PC `TooManyOperations`), und nichts wird getan. `output/result` behält seinen Wert, wie bei jedem belegten Aufruf (siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execute-a-method.html)). Bei einer streamenden Kamera passiert das oft. Stoppen Sie den Stream, bevor Sie die Methode aufrufen, oder rufen Sie sie erneut auf.
- `system/remove-module` antwortet ebenfalls mit belegt (`-1`), während ein Bild dieses Moduls gelesen wird. Stoppen Sie zuerst den Stream. Das Entfernen eines Moduls stoppt seinen Stream.
- `system/set-tessdata-dir` und `system/refresh-languages` werden vom Stream nicht aufgehalten.

Andere Module sind nicht betroffen: Jedes Modul hat seine eigene Sperre, seine eigene Engine und seinen eigenen Stream.

## Einschränkungen {#limitations}

- Ein Bild, das mit einer anderen als der angeforderten Sprache gelesen wurde, schlägt fehl, siehe [Ein in einer anderen Sprache gelesenes Bild wird verworfen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html#language).
- Der Stream wurde nur unter Windows mit LumiScan Keryx und mit simulierten Bildern getestet. Er wurde nicht unter Linux, auf dem ctrlX Data Layer oder mit einer echten Kamera verifiziert.
- LumiScan Cockpit zeichnet die Ergebnisse des Streams noch nicht.
- Von Hand an der Einstellungsdatei vorgenommene Änderungen wirken beim nächsten Start der Anwendung.
- Der Hash umfasst jede Eingabe, die das Lesen verwendet. Er ändert sich bei manchen Änderungen, die ein Ergebnis nicht verändern.

# Genau lesen – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html

OCR schlägt nicht sauber fehl. Ein Barcode wird dekodiert oder nicht; Text kommt immer mit **etwas** zurück, und eine Fehllesung sieht genauso aus wie ein korrektes Leseergebnis, bis jemand sie prüft.

Fünf Einstellungen entscheiden, ob man dem Ergebnis trauen kann. Ihre Bedeutung folgt ungefähr dieser Reihenfolge.

## 1. Auf den Text zuschneiden

`input/crop` ist hier die wirksamste Einstellung und die, die am häufigsten auf ihrem Standardwert bleibt.

Ein volles 1920x1080-Bild mit einem 200x60-Etikett gibt der Engine enorm viel Hintergrund, in dem sie Text suchen kann - und sie findet welchen: Kanten des Teils, Schatten, das Förderband. Daraus werden Wörter mit niedriger Konfidenz, die das Leseergebnis auffüllen, und sie treiben die Layout-Analyse in Richtung "das ist eine komplizierte Seite", obwohl es eine Druckzeile ist.

Schneiden Sie eng um die Stelle zu, an der der Text stehen wird. Das ist schneller und beseitigt eine ganze Klasse falscher Antworten, statt sie nachträglich zu filtern.

> [!NOTE]
> Ein Ausschnitt, der nicht in das Bild passt, wird **abgelehnt**, nicht passend gekürzt. Eine stillschweigend verkleinerte Region würde sich viel später als Wörter zeigen, die einfach fehlen.

## 2. Wenn Sie nicht zuschneiden können, die Farbkanäle zusammenführen

`input/preprocess` gibt es für einen einzigen Fehler, und der ist unangenehm: **Ein Farbbild, in dem ein Foto oder eine andere farbenfrohe Szene zusammen mit dem Text im Bild ist, kann ganz ohne Wörter zurückkommen**. Nicht verstümmelt - leer, während `status-code` Erfolg meldet. Das ist nicht von einem Bild ohne Text zu unterscheiden; es sieht also nicht nach einer Einstellung aus, die man ändern müsste, sondern danach, dass die Kamera auf das Falsche zeigt.

Gemessen an einem solchen Bild - eine Aufnahme mit 300x168 Pixeln, links ein Papageienfoto, rechts ein Titel auf einer dunklen Fläche:

| `preprocess` | Gelesen |
| --- | --- |
| `NONE` (Standard) | *gar nichts* |
| `GRAYSCALE` | `Title Of The Presentation` |
| `BINARIZE_OTSU` | `Title Of The Presentation` |

Kein `layout` und keine `engine` rettet die erste Zeile - alle 24 Kombinationen der beiden liefern nichts. Was die Engine scheitern lässt, ist die Art, wie sie ein *Farb*-Bild vor dem Lesen reduziert, nicht die Größe des Textes: Dasselbe Bild, zu Grau reduziert, wird einwandfrei gelesen, ebenso das Farbbild, auf die Fläche zugeschnitten.

> [!IMPORTANT]
> Erst zuschneiden. Der Ausschnitt löst diesen Fall in Farbe, kostet nichts und hilft aus allen oben genannten Gründen. Greifen Sie zu `preprocess`, wenn sich Text und Szene nicht durch ein Rechteck trennen lassen - ein Etikett auf einem gemusterten Teil oder ein als Ganzes fotografierter Bildschirm.

`GRAYSCALE` ist die richtige Wahl. `BINARIZE_OTSU` zwingt zusätzlich jedes Pixel auf Schwarz oder Weiß und lohnt sich nur als Versuch, wenn `GRAYSCALE` nicht geholfen hat: Es verwirft die weichen Kanten, aus denen die Engine Zeichenformen liest, und auf dem Bild oben liest es `Title 01 The`, wo `GRAYSCALE` `Title OF The` liest.

> [!NOTE]
> Keine der Einstellungen erfindet Text. Auf einem Bild ohne Text - das Foto allein oder eine gleichmäßig graue Fläche - liefern alle drei Einstellungen nichts; das Einschalten kann also kein Leseergebnis herbeizaubern.

## 3. Den Zeichensatz einschränken

`input/characters/mode` wählt einen Satz, `allow` fügt ihm Zeichen hinzu und `deny` entfernt welche.

Die klassischen OCR-Fehler sind alle Verwechslungen zwischen Zeichenklassen: `O`/`0`, `I`/`1`/`l`, `S`/`5`, `B`/`8`, `Z`/`2`. Eine Teilenummer, die immer nur aus Ziffern besteht, kann mit `mode = DIGITS` gelesen keine davon erzeugen. Das ist fast kostenlose Genauigkeit für eine einzige Einstellung.

| Kennzeichnung | Einstellung |
| --- | --- |
| Numerische Teile- oder Chargennummer | `mode = DIGITS` |
| Alphanumerischer Code in Großbuchstaben | `mode = UPPERCASE_LETTERS`, `allow = 0123456789` |
| Datumscode mit Trennzeichen | `mode = DIGITS`, `allow = /-.` |
| Alles mit festem Alphabet | `mode = CUSTOM`, `allow =` das Alphabet |
| Freier Text, für Menschen lesbar | `mode = ALL_SYMBOLS` (der Standard) |

> [!WARNING]
> **Ein leerer Zeichensatz wird abgelehnt.** `mode = CUSTOM` mit leerem `allow` oder ein `deny`, das alles entfernt, was der Modus ausgewählt hat, würde an die Engine als **gar keine Filterung** weitergegeben - das genaue Gegenteil dessen, was konfiguriert wurde, und im Ergebnis unsichtbar. Beides wird mit Statuscode `-2` abgelehnt, unter Nennung des Knotens.

## 4. Das Layout an das anpassen, was Sie betrachten

`input/layout` sagt der Engine, wie viel Struktur sie suchen soll. Der Standard ist `SINGLE_BLOCK`, weil ein zugeschnittenes Etikett ein Textblock ist.

| Wert | Verwendung für |
| --- | --- |
| `SINGLE_BLOCK` | Ein zugeschnittenes Etikett - **der Standard** |
| `SINGLE_LINE` | Eine Druckzeile, sonst nichts im Ausschnitt |
| `SINGLE_WORD` | Eine Teilenummer, ein Code |
| `SINGLE_CHAR` | Ein Zeichen, z. B. eine Nest- oder Stationsmarkierung |
| `RAW_LINE` | Eine Zeile, ohne jeden Versuch, Struktur zu finden |
| `AUTO` | Mehrere Blöcke an unbekannten Positionen |
| `SPARSE` | Über das Bild verstreuter Text ohne Layout |
| `AUTO_OSD`, `SPARSE_OSD` | Wie oben, und zusätzlich die Orientierung bestimmen |
| `SINGLE_COLUMN`, `SINGLE_BLOCK_VERT`, `CIRCLE_WORD` | Die Formen, die ihre Namen beschreiben |

Enger ist besser, wenn Sie wissen, was Sie betrachten: Der Engine zu sagen "das ist ein Wort" hindert sie daran, ein zweites zu erfinden.

> [!NOTE]
> Die `_OSD`-Varianten kosten mehr, als sie aussehen. Sie laden ein zweites Modell und verbringen Zeit damit, zu entscheiden, wie herum der Text steht. In einer Prüfzelle kommt das Teil jedes Mal gleich herum an - eine Tatsache, die die Mechanik bereits garantiert -, dafür bei jedem Lesevorgang zu bezahlen ist also Verschwendung. Verwenden Sie sie nur, wenn die Orientierung wirklich variiert.

## 5. Einen Konfidenz-Schwellwert setzen

`input/min-score` ist die Konfidenz, die ein Wort erreichen muss, um in der Wortliste zu erscheinen. **Der Standardwert ist 0**; damit wird alles gemeldet, auch Vermutungen, denen die Engine kaum traut.

Dieser Standardwert ist Absicht - eine frische Installation soll Ihnen zeigen, was sie sehen kann, statt das meiste stillschweigend zu verbergen -, aber er ist keine Produktionseinstellung.

So wählen Sie einen Wert:

1. Lassen Sie einige bekannt gute Teile mit `min-score` auf 0 durchlaufen.
2. Sehen Sie sich `mean_score` und die einzelnen Wort-Konfidenzen im Ergebnis an.
3. Ein korrektes Leseergebnis auf einem ordentlichen Bild liegt deutlich über 0,8; die Störwörter, die ein weiter Ausschnitt aufsammelt, liegen meist unter 0,5.
4. Setzen Sie den Schwellwert in die Lücke, näher an den korrekten Leseergebnissen als am Rauschen.

`min_score` wird im Ergebnis zurückgemeldet, sodass ein Leser, der eine kurze Wortliste sieht, einen strengen Schwellwert von einem schlechten Bild unterscheiden kann.

## Was das nicht behebt

- **Schlechter Kontrast, Blendung oder ein Teil außerhalb des Fokus.** Keine Einstellung holt Text zurück, den die Kamera nicht erfasst hat. Korrigieren Sie die Beleuchtung.
- **Nadeldruck- und lasergravierte Kennzeichnungen.** Daran scheitert die `LSTM`-Engine häufiger als an gedrucktem Text; `engine = LEGACY` schneidet manchmal besser ab und lohnt sich als erster Versuch.
- **Ein Teil, das sich bewegt hat.** Der Leser weiß nicht, wo das Etikett sein sollte. Wandert es aus dem Ausschnitt heraus, ist das Leseergebnis leer statt falsch - das ist der bessere Fehler und ein weiterer Grund zum Zuschneiden.

# Sprachmodelle – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html

Der Leser braucht ein Tesseract-Sprachmodell - eine `.traineddata`-Datei -, um überhaupt etwas zu lesen.

Welche Modelle installiert sind, gilt **anwendungsweit**: Zehn Module, die dieselben Etiketten lesen, wollen dieselben Modelle, also liegt die Einstellung auf `system/` und nicht einmal pro Modul.

Auf ctrlX OS wird ein Modell über die ctrlX-Dateischnittstelle hochgeladen.

Auf einem PC bedeutet ein Modell hochzuladen, seine Datei in das Verzeichnis zu kopieren, das `system/tessdata-dir` nennt.

```
hdvisionsystems/lumiscan-text-reader/system/
├── tessdata-dir              where you upload your own models   read-only
├── tessdata-dirs             every directory searched, in order read-only
├── languages                 the codes found across all of them read-only
├── set-tessdata-dir/         changes the upload directory
└── refresh-languages/        re-reads the directories
```

## Zwei Verzeichnisse, der Reihe nach durchsucht

1. **Ihr Upload-Verzeichnis**, `tessdata-dir`. Standardmäßig ist das der Ordner `tessdata` im Konfigurationsverzeichnis der Anwendung, neben der Konfigurationsdatei der Anwendung. Er wird beim ersten Start leer angelegt.

   | Plattform | Standard-`tessdata-dir` |
   | --- | --- |
   | ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-text-reader/tessdata` |
   | PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-text-reader\tessdata`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader\tessdata` |

2. **Die in der Anwendung mitgelieferten Modelle**, die schreibgeschützt sind und immer durchsucht werden.

`tessdata-dirs` zeigt beide, in der Reihenfolge, in der sie durchsucht werden.

> [!IMPORTANT]
> **Hochladen fügt Sprachen hinzu, es entfernt nie die mitgelieferten.** Sie müssen unsere Dateien nirgendwohin kopieren, und Englisch funktioniert weiter, was immer Sie tun. Ein Modell, das unter demselben Namen wie ein mitgeliefertes hochgeladen wird, gewinnt; so würden Sie Englisch durch ein anderes englisches Modell ersetzen.

## Was installiert ist

Englisch (`eng`) und `osd`. Zusammen etwa 34 MB, weshalb nur diese beiden mitgeliefert werden - jede zusätzliche Sprache würde die Anwendung für jeden Kunden vergrößern, und über das Hochladen erhalten Sie den Rest.

> [!NOTE]
> `osd` ist **keine Sprache**. Es ist das Orientierungs- und Schriftmodell, das die Layouts `AUTO_OSD` und `SPARSE_OSD` brauchen. Es erscheint in `languages`, weil es eine Datei im Verzeichnis ist, aber `input/language` auf `osd` zu setzen liest nichts.

## Eine Sprache hinzufügen

1. **Laden Sie das Modell herunter.** Das Tesseract-Projekt veröffentlicht sie unter `github.com/tesseract-ocr/tessdata_fast` und `github.com/tesseract-ocr/tessdata_best`. `fast` ist kleiner und schneller, `best` genauer; `fast` ist der richtige Standard für Bauteilkennzeichnungen.
2. **Laden Sie es hoch** in das Verzeichnis, das `system/tessdata-dir` nennt: auf ctrlX OS über die ctrlX-Dateischnittstelle, auf einem PC, indem Sie die Datei dorthin kopieren.
3. **Verwenden Sie es**: Setzen Sie `read-text/input/language` auf den Dateinamen ohne `.traineddata`.

```
upload deu.traineddata  ->  <tessdata-dir>/deu.traineddata
write  module-1/read-text/input/language = "deu"
write  module-1/read-text/execute
```

### Es gibt keinen Code nachzuschlagen

**Der Dateiname ist der Sprachcode.** Tesseract verlangt, dass das Modell für die Sprache `deu` `deu.traineddata` heißt; was immer Sie hochladen, bestimmt also, was Sie eintippen. Sie müssen nie einen Code in einer Tabelle suchen, und Sie dürfen die Datei nie umbenennen.

> [!WARNING]
> **Die Codes haben nicht alle drei Buchstaben.** Chinesisch ist `chi_sim` (vereinfacht) oder `chi_tra` (traditionell), und es gibt weitere wie `srp_latn` und `aze_cyrl`. Übernehmen Sie den Namen genau so, wie das Tesseract-Projekt ihn veröffentlicht.

| Sprache | Hochzuladende Datei | `input/language` |
| --- | --- | --- |
| Deutsch | `deu.traineddata` | `deu` |
| Französisch | `fra.traineddata` | `fra` |
| Chinesisch, vereinfacht | `chi_sim.traineddata` | `chi_sim` |
| Japanisch | `jpn.traineddata` | `jpn` |

### Kein Neustart, und auch kein Refresh

Ein hochgeladenes Modell ist **beim allernächsten `read-text`** nutzbar. Der Leser sucht die Datei bei jedem Durchlauf auf dem Datenträger, sodass eine neue gefunden wird, ohne dass etwas aktualisiert oder neu gestartet werden muss.

> [!NOTE]
> Das gilt auch für das **Ersetzen eines Modells, das bereits in Gebrauch ist**. Die Erkennungs-Engine wird einmal pro Modul aufgebaut und behalten, denn sie aufzubauen bedeutet, das Modell zu laden - 23 MB für Englisch -, und das bei jedem Lesen zu tun machte einen kleinen Lesevorgang dreimal langsamer als nötig. Sie wird neu aufgebaut, wann immer sich Sprache, Verzeichnis, Zeichensatz, Engine oder Layout ändern, und wann immer sich die Modelldatei selbst geändert hat: Vor jedem Lesen prüft der Leser Größe und Zeitstempel der Datei, und wenn sich eines davon geändert hat, vergleicht er den Inhalt der Datei mit dem, aus dem die Engine aufgebaut wurde. Eine Datei, die an Ort und Stelle überschrieben wird, unter demselben Namen im selben Verzeichnis, wird also beim nächsten `read-text` verwendet - ohne Neustart.
>
> Die Prüfung kostet einen Dateistatus pro Lesevorgang. Ein geändertes Modell wird einmal gehasht, etwa 40 ms für 23 MB, und dann geladen wie jedes neue Modell; das Protokoll meldet `The '<language>' model
> in '<directory>' changed on disk; loading it again`. Eine Datei, die nicht geladen werden kann - etwa ein noch laufender Upload -, lässt den Lesevorgang mit `-7` fehlschlagen, und der nächste Lesevorgang nach Abschluss des Uploads lädt sie.

`system/languages` ist das Einzige, das sich nicht von selbst aktualisiert - es ist eine Auflistung, die beim Start, durch `set-tessdata-dir` und durch `refresh-languages` aktualisiert wird:

```
write  system/refresh-languages/execute
read   system/languages           -> [chi_sim, deu, eng, osd]
```

Rufen Sie es auf, damit die Auflistung mit dem Verzeichnis übereinstimmt. Zum Lesen brauchen Sie es **nicht**.

## Mehrere Sprachen gleichzeitig

`input/language` ist eine Eingabe pro Modul, sodass jedes Modul in seiner eigenen Sprache aus demselben gemeinsamen Satz von Modellen liest:

```
module-1/read-text/input/language = "eng"
module-2/read-text/input/language = "deu"
module-3/read-text/input/language = "chi_sim"
```

Jedes Modul meldet in seinem eigenen `output/result.language`, was es tatsächlich verwendet hat. Zwischen ihnen wird nichts geteilt außer den Modellen auf dem Datenträger.

## Ein anderes Upload-Verzeichnis verwenden

`set-tessdata-dir` richtet das **erste** Suchverzeichnis woandershin. Auf ctrlX OS etwa auf einen USB-Stick, da die Anwendung die Schnittstelle `removable-media` hat:

```
write  system/set-tessdata-dir/input/tessdata-dir = "/media/usb/tessdata"
```

Unter Windows etwa auf einen Ordner auf einem anderen Laufwerk:

```
write  system/set-tessdata-dir/input/tessdata-dir = "D:\models\tessdata"
```

Dann, auf beiden:

```
write  system/set-tessdata-dir/execute
read   system/set-tessdata-dir/output/status-code   -> 1
read   system/languages                             -> [deu, eng, fra, osd]
```

Die mitgelieferten Modelle bleiben verfügbar, ein leeres Verzeichnis wird also akzeptiert - sinnvoll, wenn Sie kurz vor dem Hochladen darauf zeigen. Die Wahl wird gespeichert und übersteht einen Neustart.

> [!NOTE]
> Anders als bei jedem anderen Pfad, den diese Anwendung entgegennimmt, wird hier ein absoluter Pfad außerhalb des Konfigurationsverzeichnisses akzeptiert. Sprachmodelle sind große Dateien von Dritten, die berechtigterweise dort bleiben, wo sie sind - auf ctrlX OS außerhalb der ctrlX-Solution -, statt in das Konfigurationsverzeichnis kopiert zu werden. Die Anwendung listet und liest sie nur.

## osd muss neben der Sprache liegen

Tesseract löst pro Durchlauf **ein** Verzeichnis auf, die Layouts `AUTO_OSD` und `SPARSE_OSD` brauchen `osd.traineddata` also im *selben* Verzeichnis wie das Sprachmodell - nicht bloß irgendwo im Suchpfad. Laden Sie `deu.traineddata` allein hoch, wählen Sie `AUTO_OSD`, und der Durchlauf wird mit genau dieser Begründung abgelehnt:

```
error: invalid input: layout AUTO_OSD also needs osd.traineddata beside 'deu.traineddata' in
'<tessdata-dir>'; copy it from '<shipped dir>', or choose a layout that does not detect orientation
```

Laden Sie entweder `osd.traineddata` neben Ihr Modell hoch, oder verwenden Sie ein Layout, das keine Orientierung erkennt. Der Standard, `SINGLE_BLOCK`, tut das nicht - das Thema kommt nur auf, wenn Sie Orientierungserkennung angefordert haben.

## Wenn set-tessdata-dir ablehnt

Es validiert, bevor es irgendetwas veröffentlicht; ein abgelehnter Aufruf lässt `tessdata-dir`, `tessdata-dirs` und `languages` also genau so, wie sie waren - Sie sehen nie ein Verzeichnis und eine Auflistung, die sich widersprechen.

| Situation | `status-code` |
| --- | --- |
| `input/tessdata-dir` ist leer | `-2` ungültige Eingabe |
| Der Pfad ist kein Verzeichnis | `-4` Quelle nicht gefunden |
| Umgeschaltet, aber die Wahl konnte nicht gespeichert werden | `-6` Schreiben fehlgeschlagen - **die Umschaltung ist aktiv**, nur das Speichern ist fehlgeschlagen |

Ein leeres Verzeichnis wird **nicht** abgelehnt. Das war früher so, als dies der einzige Ort war, von dem Modelle gelesen wurden, und ein leeres Verzeichnis bedeutete, dass jeder Lesevorgang stillschweigend auf Englisch zurückfiel. Die mitgelieferten Modelle werden jetzt immer durchsucht.

## Die falsche Sprache

`read-text` validiert die Sprache, **bevor** es läuft, und lehnt eine nicht installierte mit `status-code -2` ab, unter Nennung jedes durchsuchten Verzeichnisses und dessen, was verfügbar ist:

```
error: invalid input: language 'fra' has no fra.traineddata in any model directory
('<tessdata-dir>', '<shipped dir>'); available: eng, osd. Upload fra.traineddata to
'<tessdata-dir>' - the file name is the language code
```

Verschwindet ein Modell zwischen dieser Prüfung und dem Lesen - jemand hat den USB-Stick gezogen -, meldet `output/result.language`, was **tatsächlich** verwendet wurde, und `status-text` sagt es ebenfalls:

```
ok: 4 word(s), mean score 0.91 (eng, SINGLE_BLOCK) - NOTE: language 'deu' is not installed, read with 'eng' instead
```

> [!IMPORTANT]
> Lesen Sie `output/result.language`, nicht `input/language`, wenn Sie wissen müssen, wie ein Ergebnis zustande kam. Meist sind sie gleich. Wenn sie sich unterscheiden, sagt nur die Ausgabe die Wahrheit.

# Modulverwaltung – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/module-management.html

Ein **Modul** ist eine konfigurierte Instanz der Anwendung. Ihm gehört die Leseoperation, mit eigenen Einstellungen und Ergebnissen:

```
hdvisionsystems/lumiscan-text-reader/<module-id>/read-text/...
```

Module können angelegt und entfernt werden, während die Anwendung läuft. Eine frische Installation stellt ein Modul bereit, mit dem Namen `module-1`.

> [!IMPORTANT]
> **Auf ctrlX OS deckt eine Lizenz zehn Module ab.** Das elfte Modul belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz auf dem Gerät es abdeckt.

Der Verwaltungsknoten liegt außerhalb der Module:

```
hdvisionsystems/lumiscan-text-reader/system/
```

## Knoten

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `modules` | string array | Die Module, die derzeit existieren |
| `create-module/execute` | Methode | Legt ein Modul und seinen Knoten-Teilbaum an |
| `create-module/input/module-id` | string | Name des anzulegenden Moduls. Nur Kleinbuchstaben, Ziffern, `-` und `_`; darf nicht `system` sein und darf noch nicht existieren |
| `remove-module/execute` | Methode | Entfernt ein Modul und seinen Knoten-Teilbaum |
| `remove-module/input/module-id` | string | Name des zu entfernenden Moduls |
| `save-current-modules/execute` | Methode | Speichert die Modulliste dauerhaft, damit beim nächsten Start dieselben Module wieder angelegt werden |
| `save-module-inputs/execute` | Methode | Speichert die Einstellungen eines Moduls dauerhaft |
| `save-module-inputs/input/module-id` | string | Name des Moduls, dessen Einstellungen gespeichert werden sollen |

Jede Methode hat außerdem `output/status-code` und `output/status-text`. Wie sich diese Module von denen der anderen LumiScan-Apps unterscheiden, ist in [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html#registry-apps) beschrieben.

## Ein Modul anlegen

1. Setzen Sie `system/create-module/input/module-id` auf den neuen Namen
2. Schreiben Sie auf `system/create-module/execute`
3. Prüfen Sie, ob `system/create-module/output/status-code` `1` ist

Das Modul ist sofort aktiv, mit Standardeinstellungen, und erscheint in `system/modules`. Es ist **nicht** dauerhaft, bis die Modulliste gespeichert wird.

Ein Modul zu entfernen ist das Spiegelbild, über `remove-module`. Ein Modul wird mit `-1` (belegt) abgelehnt, solange eine seiner eigenen Operationen läuft, statt dass seine Knoten mitten in der Ausführung zerstört werden.

> [!NOTE]
> Ein jetzt angelegtes Modul ist ein **neues** Modul: Es beginnt mit den Standard-Eingabewerten, auch wenn ein Modul dieses Namens vorher existierte und seine Einstellungen gespeichert wurden. Diese Einstellungen bleiben auf dem Datenträger, bis das Entfernen dauerhaft gemacht wird - `save-current-modules` löscht die gespeicherten Eingaben jedes Moduls, das die neue Liste nicht mehr nennt, denn bis die Liste geschrieben ist, ist ein Entfernen nicht dauerhaft, und ein Neustart bringt das Modul mit unveränderten Einstellungen zurück.

## Speichern

Zwei Dinge werden getrennt gespeichert, und beide müssen gespeichert werden, um einen Neustart zu überstehen:

- **die Modulliste** - `save-current-modules`, damit dieselben Module wieder angelegt werden;
- **die Einstellungen jedes Moduls** - `save-module-inputs`, einmal pro Modul.

So speichern Sie die Einstellungen eines Moduls:

1. Setzen Sie `system/save-module-inputs/input/module-id`
2. Schreiben Sie auf `system/save-module-inputs/execute`
3. Prüfen Sie, ob `system/save-module-inputs/output/status-code` `1` ist

Jede Eingabe dieses Moduls wird in das Konfigurationsverzeichnis der Anwendung geschrieben und beim nächsten Start wiederhergestellt. Ergebnisse werden nicht gespeichert - sie werden vom nächsten Durchlauf erzeugt.

Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen; eine ältere Konfiguration verhindert also nie den Start der Anwendung.

## Warum die Adresse auch bei einem Modul ein Modul enthält

Die Ebene `<module-id>` ist immer vorhanden, damit sich die Adressen nicht ändern, wenn ein zweites Modul hinzukommt: Ein heute gegen `module-1` geschriebenes Programm funktioniert weiter. Das entspricht auch der Pfadkonvention, die die anderen LumiScan-Anwendungen dokumentieren.

## Was Module gemeinsam haben

Module sind in allem unabhängig außer bei den Sprachmodellen: Jedes hat seine eigene Kamera, seine eigenen Leseeinstellungen, seine eigene Erkennungs-Engine und seine eigenen Ergebnisse. Die Modelle gelten anwendungsweit - `system/tessdata-dir` nennt ein Upload-Verzeichnis für die ganze Anwendung, und jedes Modul liest aus demselben Satz, jedes mit seinem eigenen `input/language`. Siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).

# Data-Layer-Referenz – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/datalayer-reference.html

Jede Adresse unten ist relativ zu

```
hdvisionsystems/lumiscan-text-reader/
```

## Data Layer {#data-layer}

LumiScan Text Reader bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-text-reader` an.

Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) nutzt LumiScan Text Reader den [ctrlX Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html).

Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzt LumiScan Text Reader [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Text Reader bietet:

- [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html)
- ein [Stream](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)-Abonnement auf eine Quelle (experimentell)

Wie Adressen aufgebaut sind, wie Funktionen aufgerufen werden, die Statuscodes und die Werkzeuge sind in [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html) beschrieben.

## Anwendungsweite Knoten

| Adresse | Typ | Zugriff | Beschreibung |
| --- | --- | --- | --- |
| `system/modules` | string[] | lesen | Die Module, die gerade existieren |
| `system/create-module/execute` | Methode | schreiben | Ein Modul hinzufügen |
| `system/create-module/input/module-id` | string | lesen/schreiben | Name für das neue Modul |
| `system/remove-module/execute` | Methode | schreiben | Ein Modul entfernen |
| `system/remove-module/input/module-id` | string | lesen/schreiben | Zu entfernendes Modul |
| `system/save-current-modules/execute` | Methode | schreiben | Die Modulliste dauerhaft speichern |
| `system/save-module-inputs/execute` | Methode | schreiben | Die Einstellungen eines Moduls dauerhaft speichern |
| `system/save-module-inputs/input/module-id` | string | lesen/schreiben | Zu speicherndes Modul |
| `system/tessdata-dir` | string | lesen | Wohin Sie eigene Modelle hochladen; das erste durchsuchte Verzeichnis |
| `system/tessdata-dirs` | string[] | lesen | Jedes durchsuchte Verzeichnis, in Reihenfolge |
| `system/languages` | string[] | lesen | In allen gefundene Sprachcodes |
| `system/set-tessdata-dir/execute` | Methode | schreiben | Ein anderes Upload-Verzeichnis verwenden |
| `system/set-tessdata-dir/input/tessdata-dir` | string | lesen/schreiben | Verzeichnis, in das hochgeladen und das zuerst durchsucht wird |
| `system/refresh-languages/execute` | Methode | schreiben | Die Verzeichnisse neu lesen und `languages` aktualisieren |
| `system/meta/subscription-schema` | string | lesen | Was der Knoten enthalten muss, den ein Modul abonniert, als JSON Schema (draft-04) seiner JSON-Form: hier ein `stream_image`, der Knoten `frame` des Stream-Ordners, mit `lineage` und `image`. Für jedes Modul dasselbe. Experimentell |

Jede Methode stellt außerdem `output/status-code` und `output/status-text` bereit.

`system/tessdata-dir`, `system/tessdata-dirs` und `system/languages` sind schreibgeschützte Ausgaben von `set-tessdata-dir` und `refresh-languages`, die Auflistung kann also nie ein Verzeichnis beschreiben, das nicht in Gebrauch ist. Beachten Sie, dass `languages` nur eine Auflistung ist: Das Lesen mit einem neu hochgeladenen Modell wartet nicht auf ein Refresh. Siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).

## Knoten pro Modul

Alle Adressen unten liegen unter `<module-id>/read-text/`.

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `execute` | Methode | - | Einen Lesevorgang ausführen |
| `input/input-image-address` | string | (leer) | Adresse des zu lesenden Bildknotens |
| `input/crop/startX` | uint16 | 0 | Linker Rand der zu lesenden Region |
| `input/crop/startY` | uint16 | 0 | Oberer Rand |
| `input/crop/width` | uint16 | 0 | Breite; 0 reicht bis zum rechten Rand |
| `input/crop/height` | uint16 | 0 | Höhe; 0 reicht bis zum unteren Rand |
| `input/language` | string | `eng` | Ein Code aus `system/languages` |
| `input/engine` | string | `DEFAULT` | `DEFAULT`, `LSTM`, `LEGACY` oder `COMBINED` |
| `input/layout` | string | `SINGLE_BLOCK` | Siehe die Tabelle unten |
| `input/preprocess` | string | `NONE` | `NONE`, `GRAYSCALE` oder `BINARIZE_OTSU` |
| `input/characters/mode` | string | `ALL_SYMBOLS` | `ALL_SYMBOLS`, `ALL_LETTERS`, `DIGITS`, `LOWERCASE_LETTERS`, `UPPERCASE_LETTERS`, `SPECIAL_SYMBOLS` oder `CUSTOM` |
| `input/characters/allow` | string | (leer) | Dem Satz hinzugefügte Zeichen |
| `input/characters/deny` | string | (leer) | Aus dem Satz entfernte Zeichen |
| `input/min-score` | float64 | 0.0 | Konfidenz, die ein Wort erreichen muss, um gemeldet zu werden, 0 bis 1 |
| `output/result` | flatbuffers | leer | `text_read_result` - das Leseergebnis |
| `output/status-code` | int16 | 0 | Ausgang als Zahl; negativ ist immer ein Fehler |
| `output/status-text` | string | (leer) | Ausgang in Worten |

### Akzeptierte Werte für `input/layout`

|   |   |
| --- | --- |
| `SINGLE_BLOCK` | Ein einheitlicher Textblock - der Standard |
| `SINGLE_LINE` | Genau eine Zeile |
| `SINGLE_WORD` | Genau ein Wort |
| `SINGLE_CHAR` | Genau ein Zeichen |
| `RAW_LINE` | Eine Zeile, ohne Strukturanalyse |
| `AUTO` | Textregionen im ganzen Bild finden und segmentieren |
| `AUTO_OSD` | Wie `AUTO`, und Orientierung und Schrift erkennen |
| `SPARSE` | Text finden, wo immer er auftritt, ohne Annahme eines Layouts |
| `SPARSE_OSD` | Wie `SPARSE`, und die Orientierung erkennen |
| `SINGLE_COLUMN` | Eine einzelne Textspalte |
| `SINGLE_BLOCK_VERT` | Ein einzelner Block vertikal ausgerichteten Textes |
| `CIRCLE_WORD` | Ein einzelnes, im Kreis angeordnetes Wort |

## Bild-Stream-Knoten pro Modul (experimentell)

Alle Adressen unten liegen unter `<module-id>/`, neben `read-text/`. Der Stream liest jedes Bild mit den Eingaben von `read-text`, allen außer `input/input-image-address`. Siehe [Text auf einem Bild-Stream lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html).

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `control/subscribe/input/enable` | bool | wie angewendet | Stream-Modus: `true` lässt den Stream laufen, `false` stoppt ihn |
| `control/subscribe/input/address` | string | wie angewendet | Die eine Quelle, der Stream-Ordner einer Kamera, z. B. `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Eine andere Adresse ersetzt sie |
| `control/subscribe/input/tag` | string | wie angewendet | Das Tag auf den Ergebnissen des Moduls: Der Schritt des Moduls in der Lineage jedes Stream-Ergebnisses trägt es. Leer: die Modul-ID, z. B. `module-1`. Ein neues Tag behält die Quelle; das nächste Ergebnis trägt es |
| `control/subscribe/input/queue-size` | uint32 | wie angewendet | Bilder, die warten dürfen, während eines gelesen wird, 1-64 |
| `control/subscribe/input/keep-latest-output` | bool | wie angewendet | `true` schreibt jedes Stream-Ergebnis zusätzlich nach `read-text/output/result` |
| `control/subscribe/execute` | Methode | - | Die Eingaben von `control/subscribe` gemeinsam prüfen, in `<module-id>.json` als `stream` speichern und dann anwenden. Eine Eingabe allein zu schreiben ändert nichts |
| `control/unsubscribe/execute` | Methode | - | Die von `control/unsubscribe/input/address` genannte Quelle entfernen, was den Stream-Modus beendet; das Tag bleibt. Wird wie ein Subscribe in `<module-id>.json` gespeichert |
| `control/unsubscribe/input/address` | string | (leer) | Die zu entfernende Quelle, wie `setting/stream/address` sie zeigt |
| `setting/stream/{enable, address, tag, queue-size, keep-latest-output}` | wie die Eingaben | `stream` in `<module-id>.json` | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat. Schreibgeschützt |
| `setting/settings-hash` | string | - | Hash dessen, womit die Ergebnisse erzeugt werden, 16 Hex-Ziffern. Schreibgeschützt |
| `control/subscribe/output/stream/active` | bool | `false` | `true`, solange der Stream läuft |
| `control/subscribe/output/stream/result` | flatbuffers | leer | `stream_texts` - eines pro gelesenem Bild. Abonnieren, um jedes zu erhalten |
| `control/subscribe/output/stream/last-failure` | string | (leer) | Warum das letzte Bild, das nicht gelesen werden konnte, fehlgeschlagen ist, mit der Quelle über ihre Adresse |
| `control/subscribe/output/stream/statistics/elapsed-ms` | uint64 | `0` | Millisekunden seit dem Start des Streams |
| `control/subscribe/output/stream/statistics/received-frames` | uint64 | `0` | Bilder, die das Abonnement geliefert hat |
| `control/subscribe/output/stream/statistics/processed-frames` | uint64 | `0` | Gelesene Bilder, jedes mit einem Ergebnis |
| `control/subscribe/output/stream/statistics/skipped-frames` | uint64 | `0` | Aus der Warteschlange verdrängte Bilder, oder wartende, als die Quelle ersetzt oder entfernt wurde |
| `control/subscribe/output/stream/statistics/failed-frames` | uint64 | `0` | Bilder, die nicht gelesen werden konnten |
| `control/subscribe/output/stream/statistics/lost-frames` | uint64 | `0` | Bilder, die verloren gingen, bevor sie eintrafen |
| `control/subscribe/output/stream/statistics/processing-us` | uint64 | `0` | Lesezeit aller gelesenen Bilder, summiert, Mikrosekunden |

Die Eingaben von `control/subscribe` beginnen mit dem, was angewendet ist, und nur `control/subscribe/execute` wendet sie an. `control/subscribe/execute` wird bei Stream-Modus ohne Adresse oder einer Warteschlangengröße außerhalb von 1-64 abgelehnt, `control/unsubscribe/execute` bei einer Adresse, die nicht die Quelle ist. Kann `<module-id>.json` nicht geschrieben werden, antworten beide mit `DL_CREATION_FAILED` (auf einem PC `CreationFailed`) und ändern nichts.

## Der Ergebnis-Flatbuffer

`output/result` ist registriert als `types/hdvisionsystems/lumiscan-text-reader/text_read_result`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `text` | string | Das gesamte Leseergebnis, Zeilen durch Zeilenumbrüche getrennt. **Nicht nach `min_score` gefiltert** |
| `words[].text` | string | Ein erkanntes Wort |
| `words[].score` | float | Seine Konfidenz, 0 bis 1 |
| `words[].bbox_x` | int | Rahmen um das Wort, in den Koordinaten der gelesenen Region |
| `words[].bbox_y` | int |   |
| `words[].bbox_width` | int |   |
| `words[].bbox_height` | int |   |
| `word_count` | uint | Wie viele Wörter gemeldet werden |
| `mean_score` | float | Mittlere Konfidenz über die gemeldeten Wörter; 0, wenn es keine gibt |
| `min_score` | float | Der angewendete Schwellwert |
| `language` | string | Die **tatsächlich** verwendete Sprache |
| `engine` | string | Die tatsächlich verwendete Engine |
| `layout` | string | Das tatsächlich verwendete Layout |
| `image_width` | uint | Die gelesene Region |
| `image_height` | uint |   |
| `timestamp` | ulong | Mikrosekunden seit der Epoche, wann der Lesevorgang abgeschlossen wurde |

`control/subscribe/output/stream/result` ist registriert als `types/hdvisionsystems/lumiscan-text-reader/stream_texts`: ein `hdv.stream.StreamTexts` mit `lineage`, woher das Bild stammt, und `result`, der Tabelle oben.

## Mit einem Beispiel beginnen (PC) {#generate-settings}

Auf einem PC schreibt der Text Reader ein Beispiel seiner Einstellungen in einen Ordner Ihrer Wahl und beendet sich, ohne zu starten. Unter Windows:

```shell
lumiscan-text-read --generate-settings C:\work\text-reader-settings
```

Ohne Ordner (`-g` allein) schreibt er in den aktuellen Ordner. Das Beispiel ist die Anwendungs-Einstellungsdatei `lumiscan-text-reader.json`, die das Modul `module-1` nennt, und die Moduldatei `module-1.json` daneben: jede Eingabe von `read-text` mit ihrem Standardwert, außer der Bildadresse, die die `camera1` des Cam Driver ist. Daneben, in `schemas/`, liegen die Schemas, die die beiden Dateien in `"$schema"` nennen: `lumiscan-text-reader.schema.json`, `lumiscan-text-reader-module.schema.json` und `stream.schema.json` für den Abschnitt `stream` einer Moduldatei. Sie beschreiben jeden Schlüssel, den der Text Reader liest - jede Eingabe von `read-text` mit ihrem Typ, ihrem Standardwert und dem Bereich, den ein Durchlauf akzeptiert -, sodass ein Editor, der JSON Schema versteht, die Dateien prüfen und zeigen kann, was jeder Wert bedeutet. Kopieren Sie den Ordner `schemas` zusammen mit den Dateien: `system/save-module-inputs` behält das `"$schema"` einer Moduldatei, die es speichert. Vorhandene Dateien werden nie überschrieben: Liegt eine davon bereits im Ordner, wird nichts geschrieben, und der Text Reader nennt welche.

Der Text Reader nennt dann den Ordner, aus dem er seine Einstellungen liest, unter Windows standardmäßig `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader`. Bearbeiten Sie das Beispiel, kopieren Sie es dorthin und starten Sie den Text Reader. Siehe auch [Speicherorte der Dateien](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files).

# Anleitung: Eine Bauteilkennzeichnung aus einem Kamerabild lesen – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/how-tos/read-a-part-marking-from-a-camera-image.html

Eine gedruckte Teilenummer aus einem Kamerabild lesen, von einer frischen Installation bis zu einer Einstellung, die Sie in die Produktion nehmen können.

Das Beispiel ist eine sechsstellige Teilenummer, auf ein Etikett gedruckt. Passen Sie Zeichensatz und Layout unterwegs an Ihre Kennzeichnung an.

## Bevor Sie beginnen

- LumiScan Cam Driver oder eine andere Bildquelle, die auf **demselben Gerät** läuft - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC - und Bilder liefert.
- Die Adresse ihres Bildknotens zur Hand, z. B. `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- Ein Teil vor der Kamera, mit der Kennzeichnung im Bild, im Fokus und gut beleuchtet.

## 1. Den Leser auf die Kamera richten

```
write  hdvisionsystems/lumiscan-text-reader/module-1/read-text/input/input-image-address
       = "hdvisionsystems/lumiscan-cam-driver/camera1/output/image"
```

## 2. Einen ersten Lesevorgang durchführen

Lassen Sie alles andere auf dem Standardwert und führen Sie ihn aus:

```
write  .../module-1/read-text/execute
read   .../module-1/read-text/output/status-code   -> 1
read   .../module-1/read-text/output/status-text
read   .../module-1/read-text/output/result
```

Ein negativer Statuscode bedeutet, dass er nicht gelaufen ist - `status-text` nennt den Grund. `-3` ist fast immer eine falsche Bildadresse.

An diesem Punkt ist das Leseergebnis meist schlecht: zu viele Wörter, manche davon Unsinn aus dem Hintergrund. Das ist zu erwarten, und die nächsten drei Schritte beheben es.

## 3. Auf die Kennzeichnung zuschneiden

Ermitteln Sie die Pixelkoordinaten des Etiketts im Bild - auf ctrlX OS zeigt die ctrlX-Kameraansicht sie an - und setzen Sie eine Region, die etwas größer ist als der Text:

```
write  .../input/crop/startX = 620
write  .../input/crop/startY = 310
write  .../input/crop/width  = 260
write  .../input/crop/height = 90
```

Führen Sie es erneut aus. Die meisten Störwörter sollten verschwunden sein.

> [!TIP]
> Dieser Schritt hilft am meisten, und er macht auch jeden Lesevorgang schneller. Kann sich das Teil zwischen den Zyklen verschieben, machen Sie den Ausschnitt groß genug, um den gesamten Bereich abzudecken, den es einnehmen kann - eine Kennzeichnung, die aus dem Ausschnitt herauswandert, wird als **nichts** gelesen, was ein besserer Fehler ist, als etwas Falsches zu lesen.

## 4. Den Zeichensatz einschränken

Eine sechsstellige Teilenummer enthält nur Ziffern, also sagen Sie das:

```
write  .../input/characters/mode = "DIGITS"
```

Das verhindert, dass `0` als `O` und `5` als `S` gelesen wird. Enthält die Nummer auch Buchstaben, verwenden Sie stattdessen `UPPERCASE_LETTERS` mit `allow = "0123456789"`, oder `CUSTOM` mit `allow` auf genau die Zeichen gesetzt, die Ihre Kennzeichnung enthalten kann.

## 5. Sagen, was betrachtet wird

Eine Druckzeile in einem engen Ausschnitt:

```
write  .../input/layout = "SINGLE_LINE"
```

Führen Sie es erneut aus. `output/result.text` sollte jetzt die Teilenummer sein und sonst nichts.

## 6. Einen Konfidenz-Schwellwert wählen

Lassen Sie fünf oder zehn bekannt gute Teile durchlaufen und notieren Sie `mean_score` aus jedem Ergebnis sowie die einzelnen `words[].score`.

Korrekte Leseergebnisse auf einem ordentlichen Bild liegen deutlich über `0.8`. Setzen Sie den Schwellwert unter Ihr schlechtestes bekannt gutes Leseergebnis und über das Rauschen:

```
write  .../input/min-score = 0.7
```

> [!NOTE]
> `min-score` filtert nur `words[]`; `text` ist immer die vollständige Ausgabe der Engine. Prüfen Sie `word_count` statt `text`, wenn Sie wissen müssen, ob das Leseergebnis gut war.

## 7. Die Einstellungen speichern

Nichts von dem oben überlebt einen Neustart, bis Sie es speichern:

```
write  hdvisionsystems/lumiscan-text-reader/system/save-module-inputs/input/module-id = "module-1"
write  hdvisionsystems/lumiscan-text-reader/system/save-module-inputs/execute
```

## 8. In das Steuerungsprogramm einbinden

Pro Zyklus:

1. Schreiben Sie `read-text/execute` - ein blockierender Aufruf, es gibt also kein Ready-Flag zu pollen.
2. Prüfen Sie `output/status-code`. Negativ bedeutet, dass der Lesevorgang fehlgeschlagen ist und nichts erzeugt hat.
3. Lesen Sie `output/result`.
4. Prüfen Sie, ob `word_count` 1 ist und `words[0].score` akzeptabel, und vergleichen Sie dann `words[0].text` mit der erwarteten Teilenummer.

Lesen Sie das Ergebnis, **bevor** Sie den nächsten Lesevorgang auslösen: Das nächste `execute` leert es.

## Fehlerbehebung

Die Probleme, die beim Einrichten eines Lesevorgangs auftreten können, sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html) beschrieben:

- [Statuscode -3 (Bild kann nicht gelesen werden)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Statuscode -2 (eine Einstellung ist unbrauchbar)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Statuscode -7 (OCR-Engine konnte nicht starten)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-7)
- [Das Leseergebnis ist leer, obwohl der Text in einem Farbbild deutlich sichtbar ist](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-colour-image)
- [Statuscode 1, aber keine Wörter](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-reading)
- [Ziffern werden als Buchstaben gelesen (O statt 0, S statt 5)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-digits-letters)
- [Das Leseergebnis enthält zusätzliche Wörter aus dem Hintergrund](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-extra-words)
- [Der Text wird in einer anderen Sprache als input/language gelesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#ts-wrong-language)
- [Das Lesen ist zu langsam](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-reading-too-slow)
- [Nadeldruck- oder lasergravierte Kennzeichnung wird schlecht gelesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-dot-matrix)

# FAQ – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/faq.html

Kurze Antworten auf häufige Fragen zu LumiScan Text Reader. Jeder Eintrag verweist auf die Seite mit den Details. Probleme und Fehlermeldungen sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html) beschrieben.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-read-text`). Um eine Fehlermeldung zu finden, durchsuchen Sie die Seite [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html) danach.

## Voraussetzungen und Einrichtung

### Welche Bildquelle und welche Pixelformate braucht der Text Reader? {#faq-image-source}

- **Antwort:** Die Anwendung liest den Bildknoten einer anderen Anwendung, die auf **demselben Gerät** läuft - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC (ein entfernter Data-Layer-Zugriff wird nicht unterstützt), normalerweise LumiScan Cam Driver, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Der Knoten muss `data` (rohe, unkomprimierte uint8-Pixeldaten), `width`, `height` und `pixel-type` bereitstellen. Unterstützte Pixelformate sind `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` und `BayerRG12`; Bayer-Bilder werden vor dem Lesen in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert. Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html)

### Welche Bildqualität braucht OCR? {#faq-image-quality}

- **Antwort:** Keine Einstellung holt Text zurück, den die Kamera nicht erfasst hat. Als Faustregel:
  - Zeichen mindestens 20 Pixel hoch, bei kleinem oder verrauschtem Druck 30 oder mehr;
  - guter Kontrast zwischen Kennzeichnung und Hintergrund;
  - Text im Fokus und nicht von der Beleuchtung überstrahlt;
  - Text ungefähr aufrecht, sofern Sie kein Layout mit Orientierungserkennung verwenden.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html)

## Text lesen

### Wie führe ich einen Lesevorgang durch und werte das Ergebnis aus? {#faq-read-text}

- **Antwort:** Setzen Sie `<module>/read-text/input/input-image-address`, schreiben Sie auf `<module>/read-text/execute` (ein blockierender Aufruf) und prüfen Sie `output/status-code`. Bei `1` lesen Sie `output/result`: `text` ist das gesamte Leseergebnis, wie die Engine es angeordnet hat, und wird **nicht** nach `min-score` gefiltert; `words[]` enthält jedes Wort mit seinem `score` und seinem Rahmen, gefiltert nach `min-score`; `word_count`, `mean_score` sowie `language`, `engine` und `layout`, wie sie tatsächlich verwendet wurden, werden ebenfalls gemeldet. In der Produktion prüfen Sie `word_count` und `words[0].score`, bevor Sie `words[0].text` mit dem erwarteten Wert vergleichen.
- **Mehr:** [Text lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html), [Anleitung: Eine Bauteilkennzeichnung aus einem Kamerabild lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/how-tos/read-a-part-marking-from-a-camera-image.html)

## Fehlerbehebung {#troubleshooting}

Probleme und Fehlermeldungen sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html) beschrieben:

- [Statuscode 1, aber keine Wörter](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-reading)
- [Das Leseergebnis ist leer, obwohl der Text in einem Farbbild deutlich sichtbar ist](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-colour-image)
- [Ziffern werden als Buchstaben gelesen (O statt 0, S statt 5)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-digits-letters)
- [Das Leseergebnis enthält zusätzliche Wörter aus dem Hintergrund](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-extra-words)
- [Nadeldruck- oder lasergravierte Kennzeichnung wird schlecht gelesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-dot-matrix)
- [Das Lesen ist zu langsam](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-reading-too-slow)
- [Statuscode -2 (eine Einstellung ist unbrauchbar)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Statuscode -3 (Bild kann nicht gelesen werden)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Statuscode -7 (OCR-Engine konnte nicht starten)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-7)
- [Ein Lesevorgang mit AUTO_OSD oder SPARSE_OSD wird abgelehnt ("also needs osd.traineddata beside …")](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-osd-beside-language)
- [Ein hochgeladenes Modell erscheint nicht auf system/languages](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-languages-list)
- [Der Text wird in einer anderen Sprache als input/language gelesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#ts-wrong-language)
- [read-text antwortet mit -1 (belegt), während der Stream läuft](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-stream-busy)
- [Ein Stream-Bild schlägt fehl mit "the frame was read with 'eng' instead and its result dropped"](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-stream-language-dropped)
- [Meine Einstellungen oder Module sind nach einem Neustart weg](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-settings-lost)

## Sprachmodelle

### Wie lese ich eine andere Sprache? {#faq-add-language}

- **Antwort:** Englisch (`eng`) und `osd` werden mit der Anwendung ausgeliefert.
  - Laden Sie die `.traineddata`-Datei von `github.com/tesseract-ocr/tessdata_fast` (kleiner und schneller, der richtige Standard für Bauteilkennzeichnungen) oder `tessdata_best` herunter.
  - Laden Sie sie, ohne sie umzubenennen, in das auf `system/tessdata-dir` genannte Verzeichnis hoch: auf ctrlX OS über die ctrlX-Dateischnittstelle, auf einem PC, indem Sie die Datei dorthin kopieren.
  - Setzen Sie `<module>/read-text/input/language` auf den Dateinamen ohne `.traineddata`, zum Beispiel `deu`. Die Codes haben nicht alle drei Buchstaben (zum Beispiel `chi_sim`).
  - Das Modell ist beim allernächsten Lesevorgang nutzbar, ohne Neustart. Hochladen entfernt nie die mitgelieferten Modelle.
- **Mehr:** [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html)

### Ich habe eine Modelldatei ersetzt - verwendet der Leser die neue? {#faq-replaced-model}

- **Antwort:** Ja, ab dem nächsten `read-text`, ohne Neustart. Die Erkennungs-Engine wird einmal pro Modul aufgebaut und behalten, aber vor jedem Lesen prüft der Leser Größe und Zeitstempel der Modelldatei und vergleicht, wenn sich eines davon geändert hat, ihren Inhalt mit dem, aus dem die Engine aufgebaut wurde. Ein geändertes Modell wird erneut geladen; das Protokoll meldet `The '<language>' model in '<directory>' changed on disk; loading it again`. Auch ein Bild-Stream liest das nächste Bild mit dem Modell, wie es auf dem Datenträger liegt.
- **Ursache:** Schlägt ein Lesevorgang direkt nach dem Ersetzen mit `-7` fehl, konnte die Datei noch nicht geladen werden - zum Beispiel bei einem noch laufenden Upload.
- **Lösung:** Lesen Sie erneut, sobald der Upload abgeschlossen ist; dieser Lesevorgang lädt das neue Modell.
- **Mehr:** [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html)

## Bild-Stream

### Wie lese ich den Text auf jedem Bild eines Kamera-Streams? {#faq-stream}

- **Antwort:** Abonnieren Sie mit einem Modul den Stream des Cam Driver (experimentell): Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, nach `<module>/control/subscribe/input/address`, setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie auf `control/subscribe/execute`. Jedes Bild wird mit den Eingaben von `read-text` gelesen, und ein Ergebnis pro Bild wird auf `control/subscribe/output/stream/result` veröffentlicht. Um das neueste Ergebnis als normales `read-text/output/result` zu lesen, setzen Sie `control/subscribe/input/keep-latest-output` auf `true`.
- **Mehr:** [Text auf einem Bild-Stream lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/processing-an-image-stream.html), [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)

## Statuscodes und Fehler

### Woran erkenne ich, ob ein Lesevorgang funktioniert hat, und wo steht der Grund für einen Fehler? {#faq-status-codes}

- **Antwort:** Prüfen Sie das Vorzeichen von `output/status-code`: größer als 0 ist Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht gelaufen ist, kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat. Der Grund steht auf `output/status-text`. Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST ein bloßes `400`), lesen Sie also anschließend `output/status-text`; der Text steht auch im Anwendungsprotokoll: auf ctrlX OS im ctrlX Logbook oder `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung. `-1` bedeutet, dass das Modul belegt war; nichts wurde getan, und das vorherige Leseergebnis bleibt unberührt. Jedes andere `execute` leert `output/result` beim Start, lesen Sie das Ergebnis also, bevor Sie den nächsten Lesevorgang auslösen.
- **Mehr:** [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execute-a-method.html), [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execution-status.html), [Text lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-text.html)

## Module, Lizenzierung und Support

### Welche Lizenz brauche ich, und wie viele Module deckt sie ab? {#faq-licence}

- **Antwort:** Eine Lizenz deckt zehn Module ab; das elfte Modul belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz auf dem Gerät es abdeckt. Bezugswege:
  - Bei HD Vision Systems gekauft: Die Lizenz liegt auf einem LumiScan Key (Windows 11 oder Ubuntu 24.04). Pro Gerät, auf dem die Software gleichzeitig läuft, ist ein LumiScan Key nötig; Keys können zwischen Geräten getauscht werden.
  - Im ctrlX Store für Windows 11 gekauft: ctrlX WORKS plus ein LumiScan Key.
  - Im ctrlX Store für ctrlX OS (ctrlX CORE oder IPC) gekauft: eine ctrlX-Lizenz, kein Key.
  - Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund wird in das Systemprotokoll geschrieben.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html#licence), [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/module-management.html), [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

### Wo finde ich weitere Antworten oder Support? {#faq-support}

- **Antwort:** Siehe die [LumiScan-FAQ](https://docs.hdvisionsystems.com/de/faq.html) der gesamten Dokumentation. Wenden Sie sich an den Customer Success von HD Vision Systems unter [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) oder +49 6221 6721905; für Lizenzen an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **Mehr:** [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

# Fehlerbehebung – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html

Diese Seite beginnt mit den allgemeinen Prüfungen, die für jedes Problem gelten. Danach folgen die Probleme, gruppiert nach Leseergebnissen, Statuscodes, Sprachmodellen, dem Bild-Stream sowie Modulen und Einstellungen. Führen Sie zuerst die allgemeinen Prüfungen durch und suchen Sie dann Ihr Symptom.

Alle Adressen sind relativ zu `hdvisionsystems/lumiscan-text-reader/`.

## Allgemeine Prüfungen {#general-checks}

- Lesen Sie `output/status-code` und `output/status-text` der Operation, für einen Lesevorgang `<module>/read-text/output/status-code` und `<module>/read-text/output/status-text`. Das Vorzeichen des Statuscodes zeigt, ob es funktioniert hat: größer als 0 ist Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht gelaufen ist, kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat. Die Codes sind unter [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/execution-status.html) aufgelistet.
- Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST ein bloßes `400`). Lesen Sie anschließend `output/status-text`: Er beginnt mit `ok:` oder `error:` und nennt den Grund.
- Lesen Sie das Anwendungsprotokoll. Auf ctrlX OS lesen Sie es im ctrlX Logbook oder mit `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung. Das Protokoll enthält denselben Text wie `output/status-text`; sind mehrere Eingaben falsch, erhält jede ihre eigene Warnzeile.
- Prüfen Sie, was der Lesevorgang tatsächlich verwendet hat: `language`, `engine` und `layout` in `output/result`. Sie entsprechen nicht immer den Eingaben, die Sie gesetzt haben.
- Prüfen Sie, ob die Bildquelle auf **demselben Gerät** läuft wie der Text Reader - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC. Ein entfernter Zugriff auf den Data Layer wird nicht unterstützt.
- Prüfen Sie die Bildqualität. Keine Einstellung stellt Text wieder her, den die Kamera nicht erfasst hat: Zeichen mindestens 20 Pixel hoch (30 oder mehr bei kleinem oder verrauschtem Druck), guter Kontrast, Text im Fokus und nicht überstrahlt, Text ungefähr aufrecht, sofern Sie kein Layout mit Orientierungserkennung verwenden. Siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html).
- Prüfen Sie die Lizenz. Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund wird in das Systemprotokoll geschrieben. Ein Modul, das keine Lizenz auf dem Gerät abdeckt, wird mit Status `-11` abgelehnt. Siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html#licence).
- Probleme, die alle LumiScan-Apps gemeinsam haben - eine App oder ein Modul fehlt im Baum, ein Knoten ist „not found", ein Methodenaufruf wird abgelehnt, ein Stream liefert nichts -, sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) im Handbuch LumiScan Keryx beschrieben.

## Leseergebnisse

### Problem: Statuscode 1, aber keine Wörter {#faq-empty-reading}

**Symptome**

`output/status-code` ist `1` (OK), aber `output/result` hat `word_count` `0`.

**Mögliche Ursachen**

- Im Bild ist nichts Lesbares: ein leerer Träger, ein falsch herum liegendes Teil oder ein Etikett außerhalb des Bildes. Das ist die normale Antwort, kein Fehler.
- Die Kennzeichnung liegt außerhalb des Ausschnitts. Eine Kennzeichnung, die aus dem Ausschnitt herauswandert, wird als nichts gelesen.
- Die Kennzeichnung ist nicht im Fokus oder steht nicht richtig herum.
- `input/min-score` filtert alle Wörter heraus. `words[]` wird nach `min-score` gefiltert; `text` nicht.
- Ein Farbbild, in dem ein Foto oder eine andere farbenfrohe Szene zusammen mit dem Text im Bild ist, siehe [Problem: Das Leseergebnis ist leer, obwohl der Text in einem Farbbild deutlich sichtbar ist](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-colour-image).

**Diagnose**

1. Prüfen Sie `text` in `output/result`. Ist `text` nicht leer, aber `word_count` `0`, wurden die Wörter gefiltert: Vergleichen Sie die Wort-Konfidenzen mit `min_score` im Ergebnis, dem angewendeten Schwellwert.
2. Prüfen Sie, ob die Kennzeichnung innerhalb von `input/crop/startX`, `input/crop/startY`, `input/crop/width` und `input/crop/height` liegt. `image_width` und `image_height` im Ergebnis zeigen die gelesene Region.
3. Prüfen Sie im Kamerabild, ob die Kennzeichnung im Fokus ist und richtig herum steht.
4. Ist das Bild ein Farbbild und Sie sehen den Text, fahren Sie mit [Problem: Das Leseergebnis ist leer, obwohl der Text in einem Farbbild deutlich sichtbar ist](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-empty-colour-image) fort.

**Lösung**

- **Wenn im Bild kein Text ist:** Das ist ein gültiges Ergebnis. Entscheiden Sie anhand von `word_count`, nicht anhand des Statuscodes, ob ein Teil Text trug.
- **Wenn die Kennzeichnung außerhalb des Ausschnitts liegt:** Machen Sie den Ausschnitt groß genug, um den ganzen Bereich abzudecken, den das Teil einnehmen kann, und lesen Sie erneut.
- **Wenn die Kennzeichnung unscharf ist oder nicht richtig herum steht:** Korrigieren Sie den Kameraaufbau. Für Text, dessen Orientierung wirklich variiert, verwenden Sie ein Layout mit Orientierungserkennung (`AUTO_OSD` oder `SPARSE_OSD`).
- **Wenn `input/min-score` alle Wörter herausfiltert:** Legen Sie den Schwellwert neu fest, wie unter [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html), Schritt 5, beschrieben.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/status-text`, dem Inhalt von `output/result` und den Werten der Knoten unter `read-text/input/`.

### Problem: Das Leseergebnis ist leer, obwohl der Text in einem Farbbild deutlich sichtbar ist {#faq-empty-colour-image}

**Symptome**

Ein Farbbild, in dem ein Foto oder eine andere farbenfrohe Szene zusammen mit dem Text im Bild ist, kommt ganz ohne Wörter zurück, während `output/status-code` Erfolg (`1`) meldet. Der Text ist nicht verstümmelt - das Leseergebnis ist leer.

**Mögliche Ursachen**

- Die Engine reduziert ein Farbbild vor dem Lesen, und mit einer farbenfrohen Szene im Bild geht dabei der Text verloren. Die Größe des Textes ist nicht die Ursache. Kein `input/layout` und keine `input/engine` lösen diesen Fall.

**Diagnose**

1. Prüfen Sie, ob `pixel-type` des Bildknotens ein Farbformat ist (zum Beispiel `RGB8` oder `BGR8`).
2. Prüfen Sie `input/preprocess`. Der Standard ist `NONE`.
3. Prüfen Sie, ob ein Rechteck den Text von der Szene trennen kann.

**Lösung**

- **Wenn ein Rechteck den Text von der Szene trennen kann:** Schneiden Sie zuerst mit `input/crop` auf den Text zu. Das Zuschneiden löst diesen Fall in Farbe.
- **Wenn sich Text und Szene nicht durch ein Rechteck trennen lassen** (zum Beispiel ein Etikett auf einem gemusterten Teil oder ein komplett fotografierter Bildschirm):
  1. Setzen Sie `input/preprocess` auf `GRAYSCALE` und lesen Sie erneut.
  2. Nur wenn `GRAYSCALE` nicht geholfen hat, versuchen Sie `BINARIZE_OTSU`.

Keine der Einstellungen erfindet Text: Bei einem Bild ohne Text liefern alle drei Einstellungen nichts.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/status-text`, den Werten von `input/crop` und `input/preprocess` und dem Pixelformat des Bildes.

### Problem: Ziffern werden als Buchstaben gelesen (O statt 0, S statt 5) {#faq-digits-letters}

**Symptome**

Zeichen werden zwischen Zeichenklassen vertauscht, zum Beispiel `O` statt `0` oder `S` statt `5`. Weitere typische Vertauschungen sind `I`/`1`/`l`, `B`/`8` und `Z`/`2`.

**Mögliche Ursachen**

- Ein unbekanntes Zeichen wird ersetzt statt abgelehnt, und der Standard von `input/characters/mode`, `ALL_SYMBOLS`, erlaubt jede Klasse.

**Diagnose**

1. Lesen Sie `input/characters/mode`, `input/characters/allow` und `input/characters/deny`. Erwartet für eine eingeschränkte Kennzeichnung: ein anderer Modus als `ALL_SYMBOLS`.

**Lösung**

- **Wenn der Zeichensatz nicht eingeschränkt ist:** Setzen Sie `input/characters/mode` passend zur Kennzeichnung:
  - numerische Teile- oder Chargennummer: `DIGITS`;
  - alphanumerischer Code in Großbuchstaben: `UPPERCASE_LETTERS` mit `input/characters/allow` = `0123456789`;
  - Datumscode mit Trennzeichen: `DIGITS` mit `allow` = `/-.`;
  - festes Alphabet: `CUSTOM` mit `allow` auf genau dieses Alphabet gesetzt.

Ein leerer Zeichensatz - `CUSTOM` mit leerem `allow` oder ein `deny`, das alles entfernt, was der Modus ausgewählt hat - wird mit Statuscode `-2` abgelehnt.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten von `input/characters/mode`, `allow` und `deny` sowie `output/result`.

### Problem: Das Leseergebnis enthält zusätzliche Wörter aus dem Hintergrund {#faq-extra-words}

**Symptome**

`output/result` enthält Wörter, die nicht zur Kennzeichnung gehören und aus dem Hintergrund stammen - Kanten des Teils, Schatten, das Förderband. Diese Wörter haben meist einen niedrigen `words[].score`.

**Mögliche Ursachen**

- `input/crop` ist zu weit oder nicht gesetzt. Alles auf null liest das ganze Bild.
- `input/layout` sucht nach mehr Struktur, als die Kennzeichnung hat.
- `input/min-score` ist `0` (der Standard), was alles meldet.

**Diagnose**

1. Prüfen Sie `input/crop` sowie `image_width` und `image_height` im Ergebnis: Sie zeigen die gelesene Region.
2. Prüfen Sie `layout` im Ergebnis.
3. Prüfen Sie den `words[].score` der zusätzlichen Wörter und `min_score` im Ergebnis. Störwörter liegen meist unter 0,5.

**Lösung**

- **Wenn der Ausschnitt zu weit ist:** Verengen Sie `input/crop` um die Stelle, an der der Text stehen wird. Das ist die wirksamste Einstellung und macht das Lesen auch schneller.
- **Wenn das Layout nicht passt:** Passen Sie `input/layout` an die Kennzeichnung an, zum Beispiel `SINGLE_LINE` für eine Druckzeile.
- **Wenn `input/min-score` zu niedrig ist:**
  1. Lassen Sie bekannt gute Teile mit `min-score` auf `0` durchlaufen.
  2. Notieren Sie `mean_score` und die einzelnen Wort-Konfidenzen im Ergebnis.
  3. Setzen Sie `input/min-score` zwischen das Rauschen (meist unter 0,5) und die korrekten Leseergebnisse (meist deutlich über 0,8), näher an die korrekten Leseergebnisse.

`min-score` filtert nur `words[]`; `text` ist immer die vollständige Ausgabe der Engine. Prüfen Sie `word_count` statt `text`, wenn Sie wissen müssen, ob das Leseergebnis gut war.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/result` und den Werten von `input/crop`, `input/layout` und `input/min-score`.

### Problem: Nadeldruck- oder lasergravierte Kennzeichnung wird schlecht gelesen {#faq-dot-matrix}

**Symptome**

Eine Nadeldruck- oder lasergravierte Kennzeichnung wird schlecht gelesen, während gedruckter Text gut gelesen wird.

**Mögliche Ursachen**

- An diesen Kennzeichnungen scheitert die `LSTM`-Engine häufiger als an gedrucktem Text.
- Beleuchtung, Kontrast oder Fokus sind schlecht. Keine Einstellung behebt das.

**Diagnose**

1. Prüfen Sie `engine` im Ergebnis: die tatsächlich verwendete Engine.
2. Prüfen Sie das Bild anhand der Regeln zur Bildqualität unter [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html): Zeichenhöhe, Kontrast, Fokus und Überstrahlung.

**Lösung**

- **Wenn die Engine die Ursache ist:** Setzen Sie `input/engine` auf `LEGACY` und vergleichen Sie die Leseergebnisse.
- **Wenn die Bildqualität schlecht ist:** Verbessern Sie Beleuchtung und Fokus.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/result` und dem Wert von `input/engine`.

### Problem: Das Lesen ist zu langsam {#faq-reading-too-slow}

**Symptome**

Der Aufruf von `read-text/execute` dauert für Ihren Zyklus zu lange. Das Lesen ist synchron: Der Aufruf kehrt zurück, wenn das Lesen abgeschlossen ist.

**Mögliche Ursachen**

- Die Engine erhält zu viel Bild. Die Lesezeit hängt vor allem davon ab, wie viel Bild die Engine erhält.
- Das Layout `AUTO_OSD` oder `SPARSE_OSD` wird verwendet. Diese Layouts laden ein zweites Modell und bestimmen zuerst die Orientierung.

**Diagnose**

1. Prüfen Sie `input/crop` sowie `image_width` und `image_height` im Ergebnis.
2. Prüfen Sie `layout` im Ergebnis.

**Lösung**

- **Wenn die Engine zu viel Bild erhält:** Verengen Sie `input/crop` um das Etikett. Ein enger Ausschnitt ist schneller und genauer als das ganze Bild.
- **Wenn ein `_OSD`-Layout verwendet wird:** Verwenden Sie ein Layout ohne Orientierungserkennung, sofern die Orientierung nicht wirklich variiert.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten von `input/crop` und `input/layout` und der Bildgröße.

## Statuscodes

### Problem: Statuscode -2 (eine Einstellung ist unbrauchbar) {#faq-status-minus-2}

**Symptome**

`output/status-code` ist `-2` (Ungültige Eingabe). `output/status-text` beginnt mit `error:` und nennt jeden beanstandeten Knoten und was erwartet wurde, zum Beispiel `min-score must be between 0 and 1, got 1.5` oder `error: crop/startX + crop/width (100 + 900 = 1000) exceeds the image width 640`.

**Mögliche Ursachen**

- Ein erforderlicher Knoten ist leer.
- Ein unbekannter Wert in `input/engine`, `input/layout`, `input/preprocess` oder `input/characters/mode`.
- Ein Wert außerhalb des Bereichs, zum Beispiel `input/min-score` außerhalb von 0 bis 1.
- Ein leerer Zeichensatz: `CUSTOM` mit leerem `allow` oder ein `deny`, das alles entfernt, was der Modus ausgewählt hat.
- Eine Sprache ohne installiertes Modell. Die Meldung nennt jedes durchsuchte Verzeichnis und was verfügbar ist, zum Beispiel `error: invalid input: language 'fra' has no fra.traineddata in any model directory ('<tessdata-dir>', '<shipped dir>'); available: eng, osd. Upload fra.traineddata to '<tessdata-dir>' - the file name is the language code`.
- Ein Layout mit Orientierungserkennung ohne `osd.traineddata` neben dem Sprachmodell, siehe [Problem: Ein Lesevorgang mit AUTO_OSD oder SPARSE_OSD wird abgelehnt ("also needs osd.traineddata beside …")](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-osd-beside-language).
- Ein Ausschnitt, der nicht in das Bild passt. Er wird abgelehnt, nicht passend gekürzt.
- Eine Bildadresse, die auf diese Anwendung selbst zeigt.
- Bei `system/set-tessdata-dir`: `input/tessdata-dir` ist leer.

**Diagnose**

1. Lesen Sie `output/status-text`. Ein Durchlauf prüft jede Einstellung und meldet **alle** Probleme auf einmal.
2. Lesen Sie das Anwendungsprotokoll: Jede falsche Eingabe hat ihre eigene Warnzeile.

**Lösung**

- **Wenn ein Wert unbekannt, außerhalb des Bereichs oder leer ist:** Korrigieren Sie jeden in `output/status-text` genannten Knoten. Die zulässigen Werte sind in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/datalayer-reference.html) aufgelistet.
- **Wenn der Zeichensatz leer ist:** Setzen Sie `input/characters/allow`, oder entfernen Sie Zeichen aus `input/characters/deny`, sodass der Zeichensatz nicht leer ist.
- **Wenn die Sprache kein Modell hat:** Laden Sie `<language>.traineddata` ohne Umbenennen in das Verzeichnis hoch, das `system/tessdata-dir` nennt, oder setzen Sie `input/language` auf einen Code aus `system/languages`. Siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).
- **Wenn der Ausschnitt nicht passt:** Ändern Sie `input/crop` so, dass `startX` + `width` und `startY` + `height` innerhalb des Bildes liegen.
- **Wenn die Bildadresse auf diese Anwendung zeigt:** Setzen Sie `input/input-image-address` auf den Bildknoten der Kameraanwendung.
- **Wenn `input/tessdata-dir` leer ist:** Schreiben Sie ein Verzeichnis auf `system/set-tessdata-dir/input/tessdata-dir` und schreiben Sie dann auf `system/set-tessdata-dir/execute`.

Führen Sie die Operation danach erneut aus und prüfen Sie, ob `output/status-code` `1` ist.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem vollständigen `output/status-text` und den Werten der Knoten unter `read-text/input/`.

### Problem: Statuscode -3 (Bild kann nicht gelesen werden) {#faq-status-minus-3}

**Symptome**

`output/status-code` ist `-3` (Bild lesen fehlgeschlagen), und das Ergebnis ist leer.

**Mögliche Ursachen**

- Eine falsche Bildadresse in `input/input-image-address`. Das ist fast immer die Ursache.
- Die Quellanwendung läuft nicht auf demselben Gerät, oder sie hat kein Bild aufgenommen.
- Der Bildknoten fehlt, ist leer oder inkonsistent.
- Das Bild verwendet ein nicht unterstütztes Pixelformat.

**Diagnose**

1. Prüfen Sie `input/input-image-address`, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
2. Prüfen Sie, ob der Bildknoten die Kinder `data`, `width`, `height` und `pixel-type` hat und ob `data` Pixeldaten enthält.
3. Prüfen Sie, ob `pixel-type` eines von `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` oder `BayerRG12` ist.
4. Prüfen Sie, ob die Quellanwendung auf demselben Gerät läuft - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC - und Bilder liefert.
5. Lesen Sie `output/status-text` für den Grund.

**Lösung**

- **Wenn die Adresse falsch ist:** Korrigieren Sie `input/input-image-address` und lesen Sie erneut.
- **Wenn die Quellanwendung nicht läuft oder kein Bild aufgenommen hat:** Starten Sie sie auf demselben Gerät, nehmen Sie ein Bild auf und lesen Sie dann erneut.
- **Wenn der Bildknoten leer oder inkonsistent ist:** Nehmen Sie mit der Quellanwendung ein neues Bild auf und lesen Sie dann erneut.
- **Wenn das Pixelformat nicht unterstützt wird:** Verwenden Sie eine Bildquelle, die eines der unterstützten Pixelformate liefert.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `input/input-image-address`, `output/status-text` sowie `pixel-type`, `width` und `height` des Bildknotens.

### Problem: Statuscode -7 (OCR-Engine konnte nicht starten) {#faq-status-minus-7}

**Symptome**

`output/status-code` ist `-7` (Algorithmus fehlgeschlagen). Das Ergebnis ist leer, und der Grund steht in `output/status-text`.

**Mögliche Ursachen**

- Die OCR-Engine konnte nicht starten, meist wegen des Verzeichnisses der Sprachmodelle.
- Ein Sprachmodell konnte nicht geladen werden, zum Beispiel ein Modell, dessen Upload noch läuft. Das passiert, wenn ein Lesevorgang direkt auf das Ersetzen eines Modells folgt.

**Diagnose**

1. Lesen Sie `output/status-text` für den Grund.
2. Prüfen Sie, ob `system/languages` nicht leer ist. `system/languages` wird nur beim Start, durch `set-tessdata-dir` und durch `refresh-languages` aktualisiert: Schreiben Sie auf `system/refresh-languages/execute`, um die Liste zu aktualisieren.
3. Prüfen Sie `system/tessdata-dirs`: jedes durchsuchte Verzeichnis, in der Reihenfolge der Suche.
4. Prüfen Sie, ob ein Upload eines Modells lief, als der Lesevorgang fehlschlug.

**Lösung**

- **Wenn ein Upload lief:** Lesen Sie erneut, sobald der Upload abgeschlossen ist. Dieser Lesevorgang lädt das neue Modell.
- **Wenn der Grund das Verzeichnis der Sprachmodelle nennt:** Prüfen Sie die Verzeichnisse auf `system/tessdata-dirs` anhand des Grundes in `output/status-text`. Haben Sie das Upload-Verzeichnis mit `system/set-tessdata-dir` geändert, prüfen Sie, ob es das Verzeichnis ist, das Ihre Modelle enthält.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem vollständigen `output/status-text` und den Werten von `system/tessdata-dir`, `system/tessdata-dirs` und `system/languages`.

## Sprachmodelle

### Problem: Ein Lesevorgang mit AUTO_OSD oder SPARSE_OSD wird abgelehnt ("also needs osd.traineddata beside …") {#faq-osd-beside-language}

**Symptome**

Ein Lesevorgang wird mit `output/status-code` `-2` und dieser Meldung abgelehnt:

```
error: invalid input: layout AUTO_OSD also needs osd.traineddata beside 'deu.traineddata' in '<tessdata-dir>'; copy it from '<shipped dir>', or choose a layout that does not detect orientation
```

**Mögliche Ursachen**

- Die Layouts `AUTO_OSD` und `SPARSE_OSD` brauchen `osd.traineddata` im **selben** Verzeichnis wie das Sprachmodell, nicht bloß irgendwo im Suchpfad. Tesseract löst pro Durchlauf ein Verzeichnis auf. Zum Beispiel wurde `deu.traineddata` allein hochgeladen.

**Diagnose**

1. Prüfen Sie `input/layout`. Erwartet bei dieser Meldung: `AUTO_OSD` oder `SPARSE_OSD`.
2. Prüfen Sie, ob das in der Meldung genannte Verzeichnis `osd.traineddata` neben dem Sprachmodell enthält.

**Lösung**

- **Wenn Sie Orientierungserkennung benötigen:** Laden Sie `osd.traineddata` in dasselbe Verzeichnis wie Ihr Modell hoch. Die Meldung nennt das mitgelieferte Verzeichnis, aus dem Sie es kopieren können. Lesen Sie dann erneut.
- **Wenn Sie keine Orientierungserkennung benötigen:** Verwenden Sie ein Layout, das keine Orientierung erkennt, etwa den Standard `SINGLE_BLOCK`.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der vollständigen Meldung und den Werten von `system/tessdata-dirs` und `system/languages`.

### Problem: Ein hochgeladenes Modell erscheint nicht auf system/languages {#faq-languages-list}

**Symptome**

Sie haben eine `.traineddata`-Datei hochgeladen, aber ihr Sprachcode ist auf `system/languages` nicht aufgeführt.

**Mögliche Ursachen**

- `system/languages` ist eine Auflistung. Sie wird nur beim Start, durch `set-tessdata-dir` und durch `refresh-languages` aktualisiert.
- Die Datei liegt nicht in dem Verzeichnis, das `system/tessdata-dir` nennt, oder sie wurde umbenannt. Der Dateiname ist der Sprachcode.

**Diagnose**

1. Prüfen Sie, ob die Datei in dem auf `system/tessdata-dir` genannten Verzeichnis liegt.
2. Prüfen Sie, ob der Dateiname unverändert ist, genau so, wie das Tesseract-Projekt ihn veröffentlicht (zum Beispiel `deu.traineddata`, `chi_sim.traineddata`).

**Lösung**

- **Wenn die Auflistung nicht aktualisiert ist:** Schreiben Sie auf `system/refresh-languages/execute` und lesen Sie dann `system/languages`. Zum Lesen brauchen Sie das nicht: Ein hochgeladenes Modell ist beim allernächsten `read-text` nutzbar.
- **Wenn die Datei in einem anderen Verzeichnis liegt oder umbenannt wurde:** Laden Sie sie erneut, ohne Umbenennen, in das Verzeichnis hoch, das `system/tessdata-dir` nennt.

`osd` erscheint in der Liste, ist aber keine Sprache: `input/language` auf `osd` zu setzen liest nichts.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten von `system/tessdata-dir`, `system/tessdata-dirs` und `system/languages` und dem Namen der hochgeladenen Datei.

### Problem: Der Text wird in einer anderen Sprache als input/language gelesen {#ts-wrong-language}

**Symptome**

`language` in `output/result` ist nicht die in `input/language` gesetzte Sprache, und `output/status-text` enthält ein `NOTE`, zum Beispiel

```
ok: 4 word(s), mean score 0.91 (eng, SINGLE_BLOCK) - NOTE: language 'deu' is not installed, read with 'eng' instead
```

**Mögliche Ursachen**

- Das Sprachmodell ist zwischen der Sprachprüfung und dem Lesen verschwunden - jemand hat zum Beispiel den USB-Stick gezogen. Die Engine liest dann mit `eng`.

**Diagnose**

1. Vergleichen Sie `language` in `output/result` mit `input/language`.
2. Lesen Sie `output/status-text` auf das `NOTE`.
3. Prüfen Sie, ob die Modelldatei noch in ihrem Verzeichnis liegt (siehe `system/tessdata-dirs`).

**Lösung**

- **Wenn das Modell verschwunden ist:** Stellen Sie das Modell in seinem Verzeichnis wieder bereit, stecken Sie zum Beispiel den USB-Stick wieder ein oder laden Sie das Modell erneut hoch. Ein hochgeladenes Modell ist beim allernächsten `read-text` nutzbar. Lesen Sie dann erneut und prüfen Sie `language` in `output/result`.

Lesen Sie `language` in `output/result`, nicht `input/language`, wenn Sie wissen müssen, wie ein Ergebnis zustande kam. Ist die Sprache gar nicht installiert, wird der Lesevorgang mit `-2` abgelehnt, siehe [Problem: Statuscode -2 (eine Einstellung ist unbrauchbar)](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-status-minus-2). Für den Bild-Stream siehe [Problem: Ein Stream-Bild schlägt fehl mit "the frame was read with 'eng' instead and its result dropped"](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#faq-stream-language-dropped).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/status-text`, `output/result` und den Werten von `input/language`, `system/tessdata-dirs` und `system/languages`.

## Bild-Stream

### Problem: read-text antwortet mit -1 (belegt), während der Stream läuft {#faq-stream-busy}

**Symptome**

Während der Bild-Stream (experimentell) läuft, wird ein Aufruf von `read-text/execute` abgelehnt:

- `output/status-code` ist `-1` (Belegt);
- der Schreibvorgang antwortet mit `DL_TOO_MANY_OPERATIONS` (ctrlX OS) oder `TooManyOperations` (PC);
- nichts wird getan, und `output/result` behält seinen Wert.

Auch `system/remove-module` antwortet mit belegt (`-1`), während ein Bild dieses Moduls gelesen wird.

**Mögliche Ursachen**

- Der Stream und `read-text` teilen sich die eine Erkennungs-Engine des Moduls und laufen auf einem Modul nie gleichzeitig. Bei einer streamenden Kamera passiert das oft.

**Diagnose**

1. Lesen Sie `control/subscribe/output/stream/active` des Moduls. `true` bedeutet, dass der Stream läuft.

**Lösung**

- **Wenn Sie `read-text` benötigen, während der Stream läuft:** Rufen Sie `read-text/execute` erneut auf, oder stoppen Sie zuerst den Stream:
  1. Setzen Sie `control/subscribe/input/enable` auf `false` und schreiben Sie auf `control/subscribe/execute`. Das Bild, das gerade gelesen wird, wird zuerst fertig gelesen.
  2. Prüfen Sie, ob `control/subscribe/output/stream/active` `false` ist.
  3. Rufen Sie `read-text/execute` auf.
- **Wenn Sie das Modul entfernen möchten:** Stoppen Sie zuerst den Stream und rufen Sie dann `system/remove-module/execute` auf.

Andere Module sind nicht betroffen: Jedes Modul hat seine eigene Sperre, seine eigene Engine und seinen eigenen Stream.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Wert von `control/subscribe/output/stream/active` und den Zählern unter `control/subscribe/output/stream/statistics/`.

### Problem: Ein Stream-Bild schlägt fehl mit "the frame was read with 'eng' instead and its result dropped" {#faq-stream-language-dropped}

**Symptome**

Ein Bild des Bild-Streams (experimentell) liefert kein Ergebnis. `control/subscribe/output/stream/statistics/failed-frames` steigt, und `control/subscribe/output/stream/last-failure` und das Protokoll melden zum Beispiel:

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: language 'deu' is no longer installed; the frame was read with 'eng' instead and its result dropped
```

**Mögliche Ursachen**

- Das Sprachmodell ist zwischen der Sprachprüfung und dem Lesen verschwunden, die Engine hat also mit `eng` gelesen. `read-text` veröffentlicht ein solches Leseergebnis mit einem `NOTE` in seinem `status-text`, aber der Stream verwirft es, weil sein Einstellungs-Hash das angeforderte Modell nennt.

**Diagnose**

1. Lesen Sie `control/subscribe/output/stream/last-failure`.
2. Prüfen Sie `control/subscribe/output/stream/statistics/failed-frames`.
3. Prüfen Sie, ob die Modelldatei für `input/language` noch in ihrem Verzeichnis liegt (siehe `system/tessdata-dirs`).

**Lösung**

- **Wenn das Modell verschwunden ist:** Stellen Sie das Modell für `input/language` in seinem Verzeichnis wieder bereit. Ein hochgeladenes Modell wird ab dem nächsten Bild verwendet. Halten Sie es verfügbar, solange der Stream läuft - ziehen Sie zum Beispiel nicht den USB-Stick, auf dem es liegt.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `control/subscribe/output/stream/last-failure`, den Zählern unter `control/subscribe/output/stream/statistics/` und den Werten von `input/language` und `system/tessdata-dirs`.

## Module und Einstellungen

### Problem: Meine Einstellungen oder Module sind nach einem Neustart weg {#faq-settings-lost}

**Symptome**

Nach einem Neustart der Anwendung fehlt ein Modul in `system/modules`, ein Modul ist mit seinen Standardeingaben zurück, oder ein Modul, das vorher gestreamt hat, streamt nicht.

**Mögliche Ursachen**

- Die Modulliste wurde nicht mit `system/save-current-modules` gespeichert. Nichts überlebt einen Neustart, bis es gespeichert ist; die Modulliste und die Einstellungen jedes Moduls werden getrennt gespeichert.
- Die Einstellungen des Moduls wurden nicht mit `system/save-module-inputs` gespeichert.
- Modus und Quelle des Bild-Streams werden von `control/subscribe/execute` in der `<module-id>.json` des Moduls gespeichert, kommen aber nur zurück, wenn auch die Modulliste gespeichert ist.
- `<module-id>.json` enthält Kommentare. Die Eingaben des Moduls werden dann beim Start nicht wiederhergestellt; das Protokoll meldet die Datei als nicht lesbar.
- Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen.

**Diagnose**

1. Lesen Sie `system/modules`.
2. Prüfen Sie das Protokoll auf eine als nicht lesbar gemeldete Moduldatei oder auf übersprungene Einstellungen.
3. Prüfen Sie, ob `<module-id>.json` im Konfigurationsverzeichnis existiert: auf ctrlX OS `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-text-reader`; auf einem PC (Windows) `%APP_RESOURCE_DIR%\etc\lumiscan-text-reader` oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader`.

**Lösung**

- **Wenn die Einstellungen des Moduls nicht gespeichert wurden:**
  1. Setzen Sie `system/save-module-inputs/input/module-id`, zum Beispiel `module-1`.
  2. Schreiben Sie auf `system/save-module-inputs/execute`.
  3. Prüfen Sie, ob `system/save-module-inputs/output/status-code` `1` ist.
- **Wenn die Modulliste nicht gespeichert wurde:** Schreiben Sie auf `system/save-current-modules/execute`. Modus und Quelle des Streams eines Moduls kommen nach einem Neustart nur zurück, wenn auch die Modulliste gespeichert ist.
- **Wenn `<module-id>.json` Kommentare enthält:** Entfernen Sie die Kommentare aus der Datei. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.

Ein mit `system/set-tessdata-dir` gewähltes Verzeichnis wird automatisch gespeichert.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `system/modules`, den Dateien im Konfigurationsverzeichnis und dem Protokoll des Starts.

## Informationen für den Support {#support-information}

Besteht ein Problem weiter, senden Sie die folgenden Informationen an den Support:

- Die Version von LumiScan Text Reader.
- Die Plattform: ctrlX OS auf einer ctrlX CORE oder einem ctrlX IPC, mit der Version von ctrlX OS; oder ein PC mit Windows 11 oder Ubuntu 24.04 und LumiScan Keryx.
- Das Anwendungsprotokoll: auf ctrlX OS aus dem ctrlX Logbook oder `journalctl`, auf einem PC die Konsolenausgabe der Anwendung.
- Datum und Uhrzeit des Fehlers.
- Den Status auf dem Data Layer: welchen Data Layer Sie verwenden (ctrlX Data Layer oder LumiScan Keryx; auf einem PC die Data-Layer-Adresse), `output/status-code` und `output/status-text` der fehlgeschlagenen Operation und bei einem abgelehnten Schreibvorgang dessen Ergebnis. Für den Bild-Stream außerdem `control/subscribe/output/stream/last-failure` und die Zähler unter `control/subscribe/output/stream/statistics/`.
- Die Konfiguration: die Werte der Knoten unter `read-text/input/`, `system/modules`, `system/tessdata-dir`, `system/tessdata-dirs` und `system/languages` sowie die Dateien im Konfigurationsverzeichnis (die Moduldateien `<module-id>.json`).

Wenden Sie sich an den Customer Success von HD Vision Systems unter [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) oder +49 6221 6721905. Für Lizenzen wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

# Release Notes: v1.1.0 – LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/release-notes/v1-1-0-2026-08-10.html

Erstes funktionsfähiges Release von LumiScan Text Reader. Frühere Versionen registrierten die Data-Layer-Knoten der Anwendung, lieferten aber ein festes Platzhalter-Ergebnis; nichts von dem Folgenden war also vorher nutzbar.

## Neu

**Text lesen.** `<module>/read-text/execute` liest den gedruckten Text in einem Kamerabild und meldet ihn doppelt: den gesamten Text, wie die Engine ihn angeordnet hat, und eine Liste pro Wort mit einer Konfidenz und einer Position für jedes Wort.

**Eine Auswahl der Erkennungs-Engine**, `input/engine`: die moderne `LSTM`-Engine mit neuronalem Netz, die ursprüngliche `LEGACY`-Engine mit Mustervergleich, beide zusammen, oder `DEFAULT`, damit die Engine selbst wählt. `LEGACY` lohnt sich als Versuch bei Nadeldruck- und lasergravierten Kennzeichnungen.

**Zwölf Text-Layouts**, `input/layout`, von `SINGLE_CHAR` bis zur Analyse ganzer Seiten mit Orientierungserkennung. Der Standard `SINGLE_BLOCK` passt zu einem zugeschnittenen Etikett.

**Eine Zeichensatz-Einschränkung**, `input/characters/mode` mit `allow` und `deny`. Eine numerische Teilenummer mit `DIGITS` zu lesen beseitigt die ganze Klasse der `O`/`0`- und `S`/`5`-Verwechslungen, statt sie nachträglich zu filtern - die günstigste verfügbare Verbesserung der Genauigkeit.

**Ein Konfidenz-Schwellwert**, `input/min-score`, damit ein Steuerungsprogramm nie ein Wort sieht, dem die Engine kaum traute. Das Ergebnis meldet den angewendeten Schwellwert, sodass sich eine kurze Wortliste von einem schlechten Bild unterscheiden lässt.

**Eine Region of Interest pro Lesevorgang**, `input/crop`, die zugleich die größte verfügbare Verbesserung der Genauigkeit und der Geschwindigkeit ist.

**Hochladbare Sprachmodelle.** Englisch und das Orientierungsmodell werden mit der Anwendung ausgeliefert, und Sie fügen weitere hinzu, indem Sie `.traineddata`-Dateien nach `…/activeConfiguration/lumiscan-text-reader/tessdata` hochladen. Hochladen **fügt** Sprachen **hinzu** - die mitgelieferten werden immer ebenfalls durchsucht, Englisch funktioniert also weiter, und Sie kopieren unsere Dateien nie irgendwohin. Der Dateiname ist der Sprachcode, es gibt also nichts nachzuschlagen: Laden Sie `deu.traineddata` hoch und setzen Sie `input/language` auf `deu`. Ein Modell ist beim allernächsten Lesevorgang nutzbar, ohne Neustart. `system/tessdata-dirs` zeigt jedes durchsuchte Verzeichnis, `system/languages`, was in ihnen gefunden wurde, und `system/set-tessdata-dir` richtet das Upload-Verzeichnis woandershin - zum Beispiel auf einen USB-Stick.

**Mehrere Module**, jedes mit eigenen Einstellungen und Ergebnissen, sodass eine Installation mehrere Kameras beobachten kann. Eine Lizenz deckt zehn Module ab.

**Ein Status bei jeder Operation**: `output/status-code` und `output/status-text`, wobei ein negativer Code immer bedeutet, dass der Durchlauf fehlgeschlagen ist und nichts erzeugt hat.

## Gut zu wissen

**Text ist kein Code.** Ein OCR-Lesevorgang liefert immer etwas, und eine Fehllesung sieht genauso aus wie ein korrektes Leseergebnis. Setzen Sie `input/characters/mode` und `input/min-score`, bevor Sie sich in der Produktion auf ein Leseergebnis verlassen - siehe [Genau lesen](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/reading-accurately.html).

**Ein leeres Leseergebnis bedeutet, dass kein Text gefunden wurde, und sonst nichts.** Jeder andere Grund, aus dem ein Durchlauf nichts erzeugen könnte - eine nicht erreichbare Kamera, eine unbrauchbare Einstellung, eine Engine, die nicht starten konnte -, wird abgefangen und als negativer Statuscode gemeldet. Ein Leser, der nicht starten konnte, meldet `-7` und nennt den Grund, statt wie ein funktionierender Leser vor einem leeren Teil auszusehen.

**Eine nicht installierte Sprache wird durch Englisch ersetzt und nicht abgelehnt.** Ein Lesevorgang validiert die Sprache vorab und lehnt eine nicht installierte ab, unter Nennung dessen, was verfügbar **ist**; und verschwindet ein Modell danach, meldet `output/result.language`, was tatsächlich verwendet wurde. Lesen Sie dieses Feld, nicht Ihre eigene Eingabe, wenn Sie wissen müssen, wie ein Leseergebnis zustande kam. Siehe [Sprachmodelle](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/language-models.html).

**Jede ungültige Eingabe wird auf einmal gemeldet**, und jede Meldung nennt den zu ändernden **Knoten** statt eines internen Feldnamens - `min-score must be between 0 and 1, got 1.5`.

**Der gesamte Text wird nicht nach dem Konfidenz-Schwellwert gefiltert**, nur die Wortliste. Sie beantworten unterschiedliche Fragen und dürfen sich berechtigterweise unterscheiden.

# LumiScan Text Reader

URL: https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Etikett mit Teilenummer, Charge und Datum; die Zeile mit der Teilenummer ist markiert](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/_images/intro/step-1.svg)<br><br>**Festlegen, wo der Text steht.** Ein Ausschnitt um die Beschriftung und die erlaubten Zeichen. | ![Die Wörter PN und 482913 umrandet, jedes mit seinem Score](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/_images/intro/step-2.svg)<br><br>**Wort für Wort lesen.** Mit einer Konfidenz für jedes Wort. | Beispielergebnis<br><br><br><br><br><br><br>Text<br>PN 482913<br><br><br>Wörter<br>2<br><br><br>Mittlerer Score<br>0.95<br><br><br>Status<br>1<br><br>**In der SPS prüfen.** Text und Score vergleichen, bevor Sie sich darauf verlassen. |

LumiScan Text Reader liest gedruckten Text wie Teilenummern, Chargen- und Datumscodes und Etiketten aus dem Kamerabild. Sie legen fest, wo der Text steht und welche Zeichen vorkommen dürfen; die App liefert den Text mit einer Konfidenz je Wort, damit Ihre SPS das Ergebnis prüfen kann. Sie läuft auf ctrlX OS oder einem Windows- oder Ubuntu-PC, mit Einstellungen für Nadel- und Lasermarkierungen.

Zur Lizenzierung siehe [Lizenz](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/lumiscan-text-reader/requirements.html#licence). Fragen? Siehe die [FAQ](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/faq.html). Ein Problem oder eine Fehlermeldung? Siehe [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-text-reader-de/1.1.0/troubleshooting.html).
