# LumiScan Template Finder 1.1.0.7 – complete documentation

> All pages of the LumiScan Template Finder 1.1.0.7 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-template-finder-de/1.1.0/

# Beschreibung – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/description.html

LumiScan Template Finder lokalisiert ein bekanntes Teil in einem Kamerabild. Sie geben der Anwendung ein kleines Bild des Teils - die **Vorlage** - und sie meldet, wo dieses Teil in einem größeren Bild erscheint, wie sicher der Treffer ist und bei welcher Skalierung und Drehung er gefunden wurde.

Typische Anwendungen sind Anwesenheitsprüfungen, Positionsrückmeldungen für einen Robotergriff und Orientierungsprüfungen vor einem Montageschritt.

Die Anwendung läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC), wo sie den ctrlX Data Layer verwendet, und auf einem PC mit Windows 11 oder Ubuntu 24.04, wo sie LumiScan Keryx verwendet. Ihre Knoten und die Art, wie sie aufgerufen werden, sind auf beiden gleich. Siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html).

Was für jede 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, was spezifisch für LumiScan Template Finder ist; seine eigenen Knoten sind in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html) aufgeführt.

## Was die Anwendung tut

Die Anwendung bietet zwei Operationen.

**Eine Vorlage erstellen** schneidet eine rechteckige Region aus einem Live-Kamerabild aus und speichert sie als PNG im Konfigurationsverzeichnis der Anwendung. So erzeugen Sie eine Vorlage von der echten Kamera, bei der echten Beleuchtung und im echten Arbeitsabstand - ohne Dateiübertragung und ohne Bildbearbeitungsprogramm. Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).

**Eine Vorlage finden** durchsucht ein Live-Kamerabild nach dieser Vorlage und meldet jedes gefundene Vorkommen. Siehe [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html).

Beide Operationen lesen das Bild im Moment ihres Aufrufs vom Data-Layer-Bildknoten einer anderen Anwendung - normalerweise LumiScan Cam Driver -, sodass sie immer mit dem aktuellen Bild arbeiten. Ein Modul kann auch jedes Bild durchsuchen, das eine Kamera streamt, siehe [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

## Woher die Bilder kommen

Die Anwendung spricht nicht selbst mit einer Kamera. Sie erhält die **Adresse** eines Bildknotens, den eine andere Anwendung veröffentlicht:

```
hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

Das trennt die beiden Aufgaben: Die Kameraanwendung ist für Triggerung und Belichtung zuständig, diese Anwendung für das Matching. Außerdem kann dasselbe Bild von mehreren Anwendungen gleichzeitig verwendet werden, und Sie können den Template Finder auf eine andere Kamera richten, indem Sie einen einzigen String ändern.

## Module

Eine Konfiguration der Anwendung ist ein **Modul**, mit eigener Vorlage, eigenen Suchparametern und eigenen Ergebnissen unter einer eigenen Adresse:

```
hdvisionsystems/lumiscan-template-finder/module-1/
```

Eine neue Installation stellt ein Modul bereit, `module-1`; weitere Module können im laufenden Betrieb angelegt werden, sodass eine Installation mehrere Kamerakonfigurationen gleichzeitig bedienen kann.

> [!IMPORTANT]
> **Auf ctrlX OS deckt eine Lizenz zehn Module ab.** Das elfte belegt eine zweite Lizenz desselben Schlüssels.

Module sind unabhängig voneinander, abgesehen davon, dass sie sich ein Vorlagenverzeichnis teilen - eine von einem Modul erstellte Vorlage kann also von allen verwendet werden. Ihre Einstellungen und die Modulliste selbst können gespeichert werden, damit sie nach einem Neustart wieder da sind. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html).

## Was ein Ergebnis enthält

Eine erfolgreiche Suche meldet für jedes gefundene Vorkommen:

- die **orientierte Bounding Box** - Mittelpunkt, Breite, Höhe und Winkel im Bild
- die **Konfidenz**, zwischen 0 und 1
- die **Skalierung** und **Drehung**, bei der der Treffer gefunden wurde

Die Ergebnisse sind nach Konfidenz sortiert, sodass der beste Treffer immer der erste Eintrag ist. Jede Operation meldet außerdem einen numerischen Statuscode und eine Statusmeldung; damit prüft eine SPS, ob der Durchlauf erfolgreich war - siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html).

# Voraussetzungen – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html

## Lizenz {#licence}

Wie LumiScan Template Finder 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-TEMPLxFDxxHDVS-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 Template Finder 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 muss für den Data Layer nichts installiert werden.

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 - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC. Ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt.

In der Praxis ist das LumiScan Cam Driver, aber jede Anwendung ist geeignet, 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 Matching in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert, sodass Vorlagen aus einem Format auch in Bildern eines anderen Formats gefunden werden.

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

## Speicherplatz

Vorlagen werden als PNG-Dateien im Konfigurationsverzeichnis der Anwendung gespeichert. Auf ctrlX OS ist dieses Verzeichnis Teil der aktiven Solution. Planen Sie Platz für die Vorlagen ein, die Sie aufbewahren wollen - eine Vorlage ist ein kleiner Ausschnitt, typischerweise einige zehn Kilobyte.

Das Verzeichnis wird beim ersten Start angelegt. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

Der Bild-Stream (experimentell) legt daneben einen weiteren Ordner an, `settings-history/`: eine kleine JSON-Datei für jeden Einstellungs-Hash, den ein Modul veröffentlicht, die nie gelöscht wird. Siehe [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

## Zeitverhalten

Das Matching ist **synchron**: Der Aufruf von `execute` kehrt zurück, wenn die Suche abgeschlossen ist. Wie lange das dauert, hängt von der Bildgröße, der Vorlagengröße und vor allem davon ab, wie groß der durchsuchte Skalierungs- und Drehungsbereich ist - die Arbeit ist ein Durchlauf pro Kombination aus Skalierung und Drehung.

Beginnen Sie mit den Standardwerten, die eine einzige Skalierung und Drehung durchsuchen, und erweitern Sie nur so weit, wie die Anwendung es tatsächlich erfordert. Siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).

# Anleitung: Ein Teil in einem Kamerabild finden – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/how-tos/match-a-part-from-a-camera-image.html

Durchgängige Anleitung von einer laufenden Kamera bis zum Matching-Ergebnis, mit dem Modul, das die Anwendung bei der Installation für Sie anlegt.

## Bevor Sie beginnen

- LumiScan Cam Driver oder eine andere Bildquelle läuft auf demselben Gerät - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC - und hat ein Bild aufgenommen.
- Sie kennen die Adresse ihres Bildknotens. Für Kamera 1 des Cam Driver:
  ```
  hdvisionsystems/lumiscan-cam-driver/camera1/output/image
  ```

Alle Pfade sind im Folgenden relativ zur Anwendung:

```
hdvisionsystems/lumiscan-template-finder/
```

Das Erstellen einer Vorlage ist eine Operation der gesamten Anwendung, unter `system/`; die Suche gehört zum Modul `module-1`.

## Schritt 1 - Beide Operationen auf die Kamera richten

Setzen Sie die Bildadresse bei beiden Operationen:

```
system/create-template/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
module-1/find-template/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

Es sind absichtlich getrennte Knoten - eine Vorlage kann aus einer Kamera ausgeschnitten und in einer anderen gesucht werden.

## Schritt 2 - Ein Bild mit dem Teil im Sichtfeld aufnehmen

Lösen Sie in der Kameraanwendung eine Aufnahme aus, mit dem Teil so positioniert, wie es in der Produktion liegen wird. Die Vorlage wird aus diesem Bild ausgeschnitten; seine Beleuchtung und sein Arbeitsabstand werden damit zur Referenz.

## Schritt 3 - Die Vorlage ausschneiden

Ermitteln Sie die Pixelkoordinaten einer Region, die das Teil enthält. Am einfachsten lesen Sie sie in der Bildvorschau der Kameraanwendung ab.

Dann:

```
system/create-template/input/crop/startX    = 100
system/create-template/input/crop/startY    = 200
system/create-template/input/crop/width     = 190
system/create-template/input/crop/height    = 100
system/create-template/input/template-name = screw
```

Schreiben Sie auf `system/create-template/execute` und lesen Sie dann `system/create-template/output/status-code`.

`1` bedeutet, dass es funktioniert hat, und `system/create-template/output/template-path` zeigt jetzt `templates/screw.png`.

Erhalten Sie `-5`, passt die Region nicht in das Bild; `output/status-text` nennt die tatsächliche Bildgröße.

## Schritt 4 - Anhand desselben Bilds prüfen

Bevor Sie etwas ändern, durchsuchen Sie das Bild, aus dem Sie eben ausgeschnitten haben:

```
module-1/find-template/input/template-name = screw
```

Schreiben Sie auf `module-1/find-template/execute` und lesen Sie `module-1/find-template/output/result`.

Sie sollten genau einen Treffer erhalten, dessen `oriented_bounding_box` in der Mitte der angegebenen Region liegt - (195, 250) für die obigen Werte - mit einer Konfidenz nahe 1.

> [!TIP]
> Diese Prüfung ist die halbe Minute wert, die sie dauert. Wird die Vorlage nicht einmal in dem Bild gefunden, aus dem sie stammt, liegt das Problem an der Region oder der Bildadresse, und keine Abstimmung der Parameter wird das beheben.

## Schritt 5 - Ein echtes Bild durchsuchen

Nehmen Sie ein neues Bild mit dem Teil in einer anderen Position auf und suchen Sie erneut. Der Treffer sollte dem Teil folgen.

Wird nichts gefunden, hat das Teil gegenüber der Vorlage wahrscheinlich Größe oder Ausrichtung geändert. Gehen Sie zu Schritt 6.

## Schritt 6 - Die Suche bei Bedarf erweitern

Nur wenn Schritt 5 fehlgeschlagen ist:

**Das Teil dreht sich.** Setzen Sie einen Drehungsbereich mit grober Schrittweite:

```
module-1/find-template/input/rotation/max-rot  = 360
module-1/find-template/input/rotation/step-rot = 5
```

**Das Teil ändert den Abstand.** Setzen Sie einen Skalierungsbereich:

```
module-1/find-template/input/scale/min-scale  = 0.9
module-1/find-template/input/scale/max-scale  = 1.1
module-1/find-template/input/scale/step-scale = 0.05
```

Jede Kombination ist ein eigener Durchlauf über das Bild; beide Einstellungen zusammen sind also 72 x 5 = 360 Durchläufe. Erweitern Sie einen Bereich nach dem anderen und hören Sie auf, sobald das Teil zuverlässig gefunden wird.

Wenn die Erweiterung des Bereichs Treffer an falschen Stellen erzeugt, erhöhen Sie den Schwellwert:

```
module-1/find-template/input/match-thresh = 0.95
```

Der Grund ist in [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html) erklärt.

## Schritt 7 - Die Einstellungen behalten

Die Einstellungen sind wirksam, aber noch nicht dauerhaft. Damit sie nach einem Neustart wiederhergestellt werden:

```
system/save-module-inputs/input/module-id = module-1
```

Schreiben Sie auf `system/save-module-inputs/execute`.

Die Vorlagendatei selbst ist bereits dauerhaft - sie ist eine Datei im Konfigurationsverzeichnis der Anwendung, das auf ctrlX OS Teil der aktiven Solution ist.

## In der Produktion

Ein Zyklus ist jetzt ein einziger Schreibvorgang auf `module-1/find-template/execute`, gefolgt von:

1. `module-1/find-template/output/status-code` lesen - negativ bedeutet, dass die Suche fehlgeschlagen ist
2. `module-1/find-template/output/result` lesen - `best_score` und `matches[0]` liefern den besten Treffer

Zwischen den Zyklen muss nichts weiter gesetzt werden. Wie jedes Bild der Kamera ohne einen Aufruf pro Bild durchsucht wird, steht in [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

# Anleitung: Sichere Ergebnisse mit der richtigen Vorlage und Szene – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/how-tos/get-reliable-results.html

LumiScan Template Finder findet ein Teil, indem er eine Vorlage, ein kleines Bild des Teils, mit dem Kamerabild vergleicht. Wie gut das gelingt, hängt weniger von den Suchparametern ab als von Vorlage und Szene: Eine Vorlage, die zur Szene passt, wird mit den Standardeinstellungen sicher gefunden; eine Vorlage, die nicht passt, lässt sich durch Abstimmen nicht retten.

Diese Seite erklärt, worauf es ankommt, und zeigt drei Beispiele. Das Vorgehen selbst - eine Vorlage ausschneiden und danach suchen - steht in [Anleitung: Ein Teil in einem Kamerabild finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/how-tos/match-a-part-from-a-camera-image.html).

## Was die Suche sicher macht {#rules}

- **Die Vorlage aus demselben Aufbau nehmen:** Schneiden Sie die Vorlage aus einem Bild der Kamera aus, die später danach sucht, mit dem Teil dort, wo es in der Produktion liegt. Beleuchtung, Arbeitsabstand und Hintergrund sind dann in Vorlage und Bild gleich. Deshalb schneidet LumiScan Template Finder die Vorlage direkt aus dem Live-Kamerabild aus, siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).
- **Das Teil in Pixeln gleich groß halten:** Das Teil muss in der Vorlage und im durchsuchten Bild etwa gleich groß erscheinen. Eine Vorlage von einer anderen Kamera, einem anderen Objektiv oder aus einem anderen Arbeitsabstand hat einen anderen Maßstab. Schwankt der Abstand in der Produktion, setzen Sie einen Skalierungsbereich, siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html#_suchbereich).
- **Die Beleuchtung konstant halten:** Schatten, Reflexionen und Helligkeitsänderungen verändern das Aussehen des Teils und senken den Score. Verwenden Sie eine eigene Beleuchtung und schirmen Sie die Station gegen Tageslicht und wechselndes Umgebungslicht ab.
- **Den Hintergrund gleich und ruhig halten:** Die Vorlage enthält etwas Hintergrund um das Teil. Weicht der Hintergrund in der Produktion von dem in der Vorlage ab, sinkt jeder Score. Ein matter, nicht spiegelnder Hintergrund in gleichmäßiger Farbe ist am besten; er hält auch Reflexionen vom Teil fern.
- **Einschließen, was das Teil kennzeichnet, ausschließen, was sich ändert:** Schneiden Sie die Vorlage eng um markante Merkmale. Hintergrund, der sich von Teil zu Teil ändert, oder Teile benachbarter Objekte gehören außerhalb der Region.

## Beispiele {#examples}

Die drei Beispiele suchen ringförmige Teile. Jedes gefundene Teil ist umrahmt und mit seinem Score beschriftet; das Teil, aus dem die Vorlage ausgeschnitten wurde, hat den Score `1.00`.

### Beispiel 1 - Vorlage aus derselben Szene, hellgrauer Hintergrund {#example-1}

|   |   |   |
| --- | --- | --- |
| ![Sechs Metallringe auf hellgrauem Hintergrund](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-grey-scene.png)<br><br>*Abbildung 1. Suchbild* | ![Vorlage: ein aus dem Suchbild ausgeschnittener Ring](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-grey-template.png)<br><br>*Abbildung 2. Vorlage* | ![Fünf Ringe umrahmt mit Scores zwischen 0.82 und 1.00; von den beiden sich berührenden Ringen unten wird nur einer gefunden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-grey-result.png)<br><br>*Abbildung 3. Ergebnis* |

Fünf der sechs Ringe werden an der richtigen Position gefunden. Von den beiden Ringen, die sich unten berühren, wird nur einer gefunden, und er wird doppelt gemeldet. Teile, die sich berühren, sind schwerer zu trennen als Teile, die einzeln liegen. Der Ring rechts, leicht schräg gesehen, hat einen niedrigeren Score (`0.87`), weil er anders aussieht als die Vorlage.

### Beispiel 2 - Vorlage aus derselben Szene, strukturierter blauer Hintergrund {#example-2}

|   |   |   |
| --- | --- | --- |
| ![Sechs Metallringe auf strukturiertem blauem Tuch](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-blue-scene.png)<br><br>*Abbildung 4. Suchbild* | ![Vorlage: ein aus dem Suchbild ausgeschnittener Ring](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-blue-template.png)<br><br>*Abbildung 5. Vorlage* | ![Alle sechs Ringe umrahmt](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-blue-result.png)<br><br>*Abbildung 6. Ergebnis* |

Alle sechs Ringe werden gefunden. Die Ringe liegen einzeln, jeder Rahmen enthält also nur einen Ring und Hintergrund. Die Scores schwanken mit den Reflexionen auf den einzelnen Ringen, von `0.72` bis `1.00`.

### Beispiel 3 - Vorlage aus einer anderen Szene {#example-3}

Die Vorlage aus Beispiel 2, auf dem blauen Hintergrund ausgeschnitten, wird im hellgrauen Bild aus Beispiel 1 gesucht.

|   |   |   |
| --- | --- | --- |
| ![Sechs Metallringe auf hellgrauem Hintergrund](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-grey-scene.png)<br><br>*Abbildung 7. Suchbild* | ![Vorlage: ein Ring auf blauem Hintergrund aus einem anderen Bild](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-blue-template.png)<br><br>*Abbildung 8. Vorlage* | ![Vier Rahmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/howto-reliable-mixed-result.png)<br><br>*Abbildung 9. Ergebnis* |

Das Ergebnis ist unbrauchbar: Zwei Ringe werden nicht gefunden, und die Rahmen sind zu groß und gegen die Ringe verschoben. Die Vorlage unterscheidet sich von der Szene im Hintergrund, in der Beleuchtung und in der Größe - der Ring ist in Pixeln größer als die Ringe im Suchbild. Der beste Treffer einer Suche hat immer einen Score nahe `1.00`; ein hoher Score allein beweist also keine richtige Position, siehe [Die Konfidenz verstehen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html#_die_konfidenz_verstehen).

Abhilfe schafft kein Parameter, sondern eine neue Vorlage, ausgeschnitten aus der grauen Szene.

## Checkliste {#checklist}

1. Die Vorlage ist mit der suchenden Kamera im Produktionsaufbau ausgeschnitten.
2. Das Teil ist in Vorlage und Bild in Pixeln etwa gleich groß. Andernfalls ist ein Skalierungsbereich gesetzt.
3. Die Beleuchtung ist beim Ausschneiden der Vorlage und in der Produktion gleich.
4. Der Hintergrund ist gleich, matt und gleichmäßig.
5. Die Vorlage wird im Bild, aus dem sie stammt, in der Mitte der Region mit einem Score nahe `1` gefunden.

Wird das Teil trotzdem nicht oder an falschen Stellen gefunden, siehe [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html).

# Eine Methode ausführen – LumiScan Template Finder

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

Jede Operation dieser Anwendung - Matching, Erstellen einer Vorlage und Modulverwaltung - wird auf dieselbe Weise gestartet und meldet ihr Ergebnis auf dieselbe Weise.

## Der Aufbau einer Operation

Eine Operation liegt unter einer 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/` - ein Matching-Ergebnis oder den Pfad einer geschriebenen Datei -, 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 erfolgreich war.

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, sodass eine wiederholte Operation nur Schritt 2 benötigt.

## Das Ergebnis prüfen

`output/status-code` ist eine vorzeichenbehaftete Zahl, und **das Vorzeichen allein sagt Ihnen, ob die Operation erfolgreich war**:

| Wert | Bedeutung |
| --- | --- |
| größer als 0 | Die Operation war erfolgreich |
| 0 | Die Operation wurde seit dem Start der Anwendung nicht ausgeführt |
| 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 fehlende Vorlage anders als auf eine Kamera, die nicht antwortet.

`output/status-text` enthält dasselbe Ergebnis als Satz und nennt den fehlerhaften Wert, wenn es einen gibt:

```
ok: 3 match(es) using 'screw.png'
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, denn der Wortlaut kann sich zwischen Releases ändern. Die vollständige Liste der Codes steht in [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html).

> [!NOTE]
> Der Grund kommt auf `output/status-text` an, nicht in der Antwort auf den Schreibvorgang auf `execute` selbst. Ein fehlgeschlagener Schreibvorgang antwortet nur mit einem Statuscode - über REST ein bloßes `400`. Der Data Layer verwirft alle Details, die ein Provider an einen fehlgeschlagenen Aufruf anhängt; `output/status-text` anschließend zu lesen ist also der Weg, um herauszufinden, was falsch war. Die Ergebniscodes eines Schreibvorgangs auf beiden Data Layern sind in [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results) aufgeführt.
>
> Derselbe Text wird in das Protokoll der Anwendung geschrieben, sodass ein Fehler auch ganz ohne den Data Layer diagnostizierbar ist: auf ctrlX OS im ctrlX Logbook oder mit `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung. Sind mehrere Eingaben falsch, erhält jede eine 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, sodass verschiedene Module parallel matchen - eine zweite Kamera wird nicht von der ersten aufgehalten. `system/create-template` hat eine eigene Sperre; das Erstellen einer Vorlage blockiert also das Matching nicht, und zwei Erstellungen können nicht kollidieren.

## Die Ausgaben gehören zum Durchlauf, der gerade beginnt

Jede Methode löscht ihre eigenen Ausgabeknoten, sobald sie beginnt - `find-template` sein `output/result`, `create-template` seinen `output/template-path`. Sie werden gelöscht, **bevor** irgendetwas fehlschlagen kann; ein Durchlauf, der aus irgendeinem Grund fehlschlägt, hinterlässt sie also leer, statt das Ergebnis eines früheren Durchlaufs zu behalten.

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

`output/status-code` und `output/status-text` sind die Ausnahme - sie beschreiben immer den letzten Versuch, und genau dafür sind sie da.

> [!WARNING]
> **Lesen Sie eine Ausgabe, bevor Sie den nächsten Durchlauf auslösen.** Die Ausgaben beschreiben den letzten Durchlauf, und der nächste Aufruf leert sie in dem Moment, in dem er beginnt. Wer `execute` erneut aufruft und dann das vorherige Ergebnis lesen will, erhält nichts.
>
> Der einzige Fall, der **nichts** löscht, ist ein als `-1` (belegt) abgelehnter Aufruf: Er wurde nie ausgeführt und lässt die Ausgaben der laufenden Operation unberührt. Ein zweites `execute` unmittelbar nach dem ersten hat also zwei mögliche Ergebnisse, 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 löscht die Ausgaben, die der erste Durchlauf eben 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 Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html

Jede Operation meldet ihr Ergebnis auf zwei Knoten neben sich: `output/status-code` für Ihr Programm und `output/status-text` für einen Menschen.

## Statuscodes

| Code | Bedeutung | Wann er auftritt |
| --- | --- | --- |
| `0` | Idle | Die Operation wurde seit dem Start der Anwendung nicht ausgeführt |
| `1` | OK | Die Operation wurde abgeschlossen. Eine Suche kann trotzdem nichts 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, sobald sie abgeschlossen ist |
| `-2` | Ungültige Eingabe | Ein Eingabewert kann nicht verwendet werden - ein erforderlicher Knoten ist leer, ein unbekannter Matching-Modus, eine Bildadresse, die auf diese Anwendung selbst zeigt, oder ein Verzeichnispfad, der absolut ist oder aus dem Konfigurationsverzeichnis hinausführt |
| `-3` | Bild konnte nicht gelesen werden | Der Bildknoten an der angegebenen Adresse fehlt, ist leer oder inkonsistent oder verwendet ein nicht unterstütztes Pixelformat. Prüfen Sie, dass die Kameraanwendung läuft und ein Bild aufgenommen hat |
| `-4` | Quelle nicht gefunden | Das Vorlagenverzeichnis oder die Vorlagendatei fehlt oder ist nicht lesbar. Prüfen Sie den Namen anhand von `system/templates` und prüfen Sie `system/template-dir`: Alle Module teilen sich ein Vorlagenverzeichnis |
| `-5` | Ungültige Ausschnittsregion | Die Region of Interest passt nicht in das Bild. Die Meldung nennt die tatsächliche Bildgröße |
| `-6` | Schreiben fehlgeschlagen | Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger |
| `-7` | Algorithmus fehlgeschlagen | Das Matching selbst ist fehlgeschlagen |
| `-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` auf 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-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html) |

Diese Codes sind der eigene Ausführungsstatus der Finder, nicht die Modul-Statuscodes des Cam Driver oder von AI Object Matching: `-5` bedeutet hier eine ungültige Ausschnittsregion. Siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

> [!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 die Prüfung des **Vorzeichens** der robustere Test: `status-code < 0` bleibt auch dann richtig, wenn ein Release einen Fehler einführt, den Ihr Programm noch nie gesehen hat.

## Welche Operation welche Codes meldet

| Operation | Mögliche Codes |
| --- | --- |
| Eine Vorlage finden | `1`, `-1`, `-2`, `-3`, `-4`, `-7`, `-8` |
| Eine Vorlage erstellen | `1`, `-1`, `-2`, `-3`, `-5`, `-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 Werte bleiben erhalten, bis diese Operation erneut ausgeführt wird. Eine fehlgeschlagene Vorlagenerstellung stört daher nicht das Ergebnis der letzten Suche.

# Eine Vorlage erstellen – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html

Eine Vorlage ist ein kleines Bild des Teils, das Sie finden wollen. Diese Operation schneidet eine Vorlage aus einem Live-Kamerabild aus und speichert sie; die Vorlage stammt also von der echten Kamera bei der echten Beleuchtung.

Die Operation gehört zur gesamten Anwendung, nicht zu einem Modul, und liegt deshalb auf dem Systemknoten:

```
hdvisionsystems/lumiscan-template-finder/system/create-template/
```

## Eingaben

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/input-image-address` | string | *(leer)* | Data-Layer-Adresse des Bilds, aus dem ausgeschnitten wird. Erforderlich |
| `input/crop/startX` | int32 | `0` | Linker Rand der Region, in Pixeln vom linken Bildrand |
| `input/crop/startY` | int32 | `0` | Oberer Rand der Region, in Pixeln vom oberen Bildrand |
| `input/crop/width` | int32 | `0` | Breite der Region in Pixeln. Muss größer als 0 sein |
| `input/crop/height` | int32 | `0` | Höhe der Region in Pixeln. Muss größer als 0 sein |
| `input/template-name` | string | *(leer)* | Name, unter dem gespeichert wird. `.png` wird angehängt, wenn Sie keine Erweiterung angeben. Verwenden Sie einen Namen in Kleinbuchstaben: Nur `.png`-Dateien in Kleinbuchstaben erscheinen auf `system/templates`. Erforderlich |

Die Vorlage wird in `system/template-dir` geschrieben, das sich die gesamte Anwendung teilt; sie ist also für jedes Modul nutzbar, sobald sie gespeichert ist.

## Ausgaben

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `output/template-path` | string | Pfad der geschriebenen Datei, relativ zum Konfigurationsverzeichnis |
| `output/status-code` | int16 | Ausführungsstatus |
| `output/status-text` | string | Dasselbe Ergebnis in Worten |

`output/template-path` ist so aufgeteilt, wie die Suche es erwartet: `templates/screw.png` bedeutet, das Vorlagenverzeichnis der Suche auf `templates` und ihren Vorlagennamen auf `screw.png` zu setzen.

## Vorgehen

1. Stellen Sie sicher, dass die Kameraanwendung ein Bild aufgenommen hat.
2. Setzen Sie `input/input-image-address`.
3. Setzen Sie die vier Werte unter `input/crop/` auf die Region, die das Teil enthält.
4. Setzen Sie `input/template-name`.
5. Schreiben Sie auf `system/create-template/execute`.
6. Lesen Sie `output/status-code`. Bei `1` benennt `output/template-path` die neue Vorlage.

> [!TIP]
> Durchsuchen Sie sofort **dasselbe Bild** nach der eben ausgeschnittenen Vorlage. Sie muss genau in der Mitte der angegebenen Region gefunden werden, mit einer Konfidenz nahe 1. Ist das nicht der Fall, liegt das Problem an der Region oder der Bildquelle - nicht an den Suchparametern. Das dauert wenige Sekunden und erspart später viel Rätselraten.

## Eine gute Region wählen

- **Nehmen Sie auf, was das Teil kennzeichnet, und lassen Sie weg, was variiert:** Hintergrund, der sich von Teil zu Teil ändert, senkt jeden Score.
- **Halten Sie die Region klein, aber markant:** Der Matching-Aufwand wächst mit der Fläche der Vorlage. Ein kleines, kontrastreiches Merkmal ist schneller und zuverlässiger als das ganze Teil.
- **Halten Sie Abstand zum Bildrand:** Eine Vorlage, die den Bildrand berührt, kann nahe dem gegenüberliegenden Rand nicht gefunden werden, weil die Vorlage vollständig in das durchsuchte Bild passen muss.
- **Denken Sie an das Binning:** Wenn die Suche mit Binning läuft, muss die Vorlage nach dem Herunterskalieren noch erkennbar sein. Bei einer Bin-Größe von 4 wird aus einem 20 Pixel breiten Merkmal eines mit 5 Pixeln.

## Geschriebene Datei

Die Region wird als Standard-PNG mit 8-Bit-RGB geschrieben, unabhängig vom Pixelformat der Kamera - Bayer-Bilder werden vorher in Farbe umgewandelt und 12-Bit-Bilder herunterskaliert.

Das Zielverzeichnis wird angelegt, wenn es nicht existiert.

> [!WARNING]
> Eine vorhandene Datei mit demselben Namen wird ohne Warnung überschrieben. Verwenden Sie einen neuen Vorlagennamen, wenn Sie die alte Vorlage behalten wollen.

# Eine Vorlage finden – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html

Durchsucht ein Live-Kamerabild nach einer gespeicherten Vorlage und meldet jedes gefundene Vorkommen.

Adresse, relativ zum Modul:

```
find-template/
```

## Eingaben

Die beiden erforderlichen Werte sind das zu durchsuchende Bild und die gesuchte Vorlage. Alles andere hat einen funktionierenden Standardwert; die Parameter, die die Suche selbst steuern, sind in [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html) beschrieben.

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/input-image-address` | string | *(leer)* | Data-Layer-Adresse des zu durchsuchenden Bilds. Erforderlich |
| `input/template-name` | string | *(leer)* | Gesuchte Vorlage, wie auf `system/templates` aufgeführt. `.png` wird angehängt, wenn Sie keine Erweiterung angeben. Erforderlich |

Das Verzeichnis, aus dem sie gelesen wird, ist `system/template-dir`, das sich die gesamte Anwendung teilt - siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

## Ausgaben

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `output/result` | flatbuffer | Die gefundenen Treffer, nach Konfidenz sortiert |
| `output/status-code` | int16 | Ausführungsstatus |
| `output/status-text` | string | Dasselbe Ergebnis in Worten |

## Das Ergebnis

`output/result` ist ein FlatBuffer vom Typ `hdv.template_match.Result`:

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `matches` | array | Ein Eintrag pro gefundenem Vorkommen, nach Konfidenz sortiert, höchste zuerst |
| `best_index` | ulong | Index des besten Treffers. Immer `0`, weil die Liste sortiert ist |
| `best_score` | float | Konfidenz des besten Treffers, oder `0.0`, wenn nichts gefunden wurde |
| `template_name` | string | Die für diesen Durchlauf verwendete Vorlage |
| `match_mode` | string | Der verwendete Matching-Algorithmus |
| `match_thresh` | float | Der angewendete Schwellwert |
| `image_width`, `image_height` | uint | Größe des durchsuchten Bilds, damit Koordinaten normalisiert werden können |
| `timestamp` | ulong | Mikrosekunden seit der Epoche, aufgenommen beim Abschluss der Suche |

Jeder Eintrag in `matches` enthält:

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `oriented_bounding_box` | struct | `center_x`, `center_y`, `width`, `height` in Pixeln und `angle` in **Grad** |
| `confidence` | float | Treffer-Score zwischen 0 und 1 |
| `scale` | float | Der Skalierungsfaktor der Vorlage, bei dem dieser Treffer gefunden wurde |
| `rotation` | float | Die Drehung der Vorlage, bei der dieser Treffer gefunden wurde, in Grad |

> [!NOTE]
> Eine leere Liste `matches` zusammen mit Statuscode `1` bedeutet, dass die Suche korrekt gelaufen ist und nichts gefunden hat. Das ist ein normales Ergebnis - das Teil ist einfach nicht da oder nicht ähnlich genug, um den Schwellwert zu überschreiten. Es ist kein Fehler.

## Vorgehen

1. Setzen Sie `input/input-image-address` und `input/template-name`.
2. Passen Sie die Suchparameter an, wenn die Standardwerte nicht passen - siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).
3. Schreiben Sie auf `find-template/execute`.
4. Lesen Sie `output/status-code`. `1` bedeutet, dass die Suche gelaufen ist.
5. Lesen Sie `output/result` für die Treffer oder `output/status-text`, wenn der Statuscode negativ war.

Einmal gesetzte Eingaben behalten ihre Werte; eine wiederholte Suche ist also ein einziger Schreibvorgang auf `execute`.

## Häufige Fehler

Fehler sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html) beschrieben:

- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Statuscode `-3` (Bild konnte nicht gelesen werden)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Statuscode `-4` (Quelle nicht gefunden)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-4)
- [Das Ergebnis ist leer, obwohl der Statuscode `1` ist](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-empty-result)

## Nur einen Teil des Bilds durchsuchen

`input/crop/` beschränkt die Suche auf ein Rechteck - das ist schneller und vermeidet Treffer auf einem Teil, das zufällig an anderer Stelle im Bild erscheint. Alle vier Werte sind `uint16`.

Eine **Breite oder Höhe von null bedeutet "bis zum Bildrand"** auf dieser Achse:

| Einstellung | Durchsuchte Region |
| --- | --- |
| alle vier null (Standard) | das ganze Bild |
| `startX=100, startY=50`, Größen null | von (100, 50) bis zur unteren rechten Ecke |
| `width=0, height=200` | ein 200 Pixel hohes Band bis zum rechten Rand |

Eine Region, die über einen Rand hinausreicht, wird **abgelehnt, nicht beschnitten** - ein kleinerer Suchbereich als angefordert würde sich erst viel später bemerkbar machen, als Treffer, die einfach fehlen. Der Grund nennt die Eingabe und die verletzte Grenze, zum Beispiel `crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640`. Eine Region, die kleiner als die Vorlage ist, wird ebenfalls abgelehnt, mit Status `-5`.

## Auf welches Bild sich die Positionen beziehen

`input/result-coordinate` legt fest, worauf sich die Positionen in `output/result` beziehen:

| Wert | Bedeutung |
| --- | --- |
| `IMAGE` (Standard) | Das ganze Bild unter `input-image-address`; eine Position kann so unabhängig von der Ausschnittsregion direkt für einen Robotergriff verwendet werden |
| `CROP` | Die durchsuchte Region, deren obere linke Ecke (0,0) ist |

Die Einstellung ändert nur, wie das Ergebnis gemeldet wird, nie, was gefunden wird. `image_width` und `image_height` im Ergebnis folgen derselben Wahl.

## Was eine fehlgeschlagene Suche hinterlässt

Die Treffer werden gelöscht, bevor die Suche beginnt; ein Durchlauf, der aus irgendeinem Grund fehlschlägt, hinterlässt `output/result` also leer, statt die Treffer eines früheren Bilds zu behalten. Wer das Ergebnis liest, ohne `output/status-code` zu prüfen, sieht daher nichts und keinen veralteten Treffer.

Status `-1` (belegt) ist die Ausnahme: Dieser Aufruf wurde nie ausgeführt und lässt das Ergebnis der laufenden Suche unberührt.

## Jedes Bild einer Kamera durchsuchen

`find-template` durchsucht ein Bild pro Aufruf. Wie ein Modul jedes Bild durchsucht, das eine Kamera streamt, mit denselben Eingaben, steht in [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

# Vorlagen in einem Bild-Stream finden (experimentell) – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/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.

`find-template` durchsucht ein Bild pro Aufruf: Ihr Programm setzt `input/input-image-address` und schreibt auf `execute`. Ein Bild-Stream funktioniert umgekehrt. Der Cam Driver veröffentlicht jedes aufgenommene Bild 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, durchsucht jedes Bild, sobald es eintrifft, und veröffentlicht ein Ergebnis pro Bild auf `control/subscribe/output/stream/result`.

Jedes Bild wird mit den Eingaben von `find-template` durchsucht, wie sie in diesem Moment sind: die Vorlage, die Ausschnittsregion, die Skalierungs- und Drehungsbereiche und jeder andere Knoten unter `find-template/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 durchsucht.

Jedes Ergebnis trägt die Lineage seines Bilds - 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-template-finder-de/1.1.0/lumiscan-template-finder/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 durchsucht, nimmt es jedes Mal, wenn die vorherige Suche abgeschlossen ist, das neueste Bild. Die Bilder dazwischen werden als übersprungen gezählt. Wie viele Bilder warten dürfen, legt die Warteschlangengröße fest, siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/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 Stream-Knoten und das Starten und Stoppen eines Streams sind in jeder LumiScan-App gleich, die einen Stream konsumiert; [Streams (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) im Data-Layer-Handbuch beschreibt sie allgemein. Diese Seite beschreibt, was für den Template Finder besonders ist.

## 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 folgenden Adressen beginnen mit `hdvisionsystems/lumiscan-template-finder/<module-id>/`. Sie liegen neben `find-template/`, 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. Nur eine Eingabe zu schreiben ändert nichts. Siehe [Die Quelle ändern](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die von `control/unsubscribe/input/address` genannte Quelle, 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 durchsucht wird: `1` bis `64`. Siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#queue-size). |
| `control/subscribe/input/keep-latest-output` | bool | `true`, um jedes Stream-Ergebnis zusätzlich auf `find-template/output/result` zu schreiben. Siehe [Die neueste Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#keep-latest-output). |

Die Eingaben beginnen mit dem, was beim Start der Anwendung angewendet ist, sodass ein Client eine von ihnen ändern und die Methode ausführen kann.

Was die Quelle enthalten muss: Lesen Sie `hdvisionsystems/lumiscan-template-finder/system/meta/subscription-schema`, für jedes Modul gleich. 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-template-finder-de/1.1.0/lumiscan-template-finder/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 `/` am Anfang oder Ende 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, wie die Einstellungsdatei es enthält. Schreibgeschützt. |
| `setting/settings-hash` | string | Der Hash dessen, womit die Ergebnisse erzeugt werden, als 16 Hexadezimalziffern. Schreibgeschützt. Siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/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` | flatbuffer `stream_template_matches` | Die in jedem Bild gefundenen Treffer und die Lineage des Bilds. Abonnieren Sie den Knoten, um jedes Ergebnis zu erhalten. Siehe [Das Ergebnis eines Bilds](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#result). |
| `control/subscribe/output/stream/last-failure` | string | Warum das letzte Bild, das nicht durchsucht werden konnte, fehlgeschlagen ist. Nennt die Quelle anhand ihrer Adresse, siehe [Das Ergebnis eines Bilds](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/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-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#statistics). |

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

## Einrichtung {#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 `find-template` wie für eine einzelne Suche, siehe [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html). Ein Aufruf von `find-template/execute` auf das `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`, auf `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. Von da an treffen die Ergebnisse ein.
6. Zum Stoppen setzen Sie `control/subscribe/input/enable` auf `false` und schreiben erneut auf `control/subscribe/execute`. Das gerade durchsuchte Bild wird zuerst fertig bearbeitet.

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

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

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

`krxclient subscribe` zeigt einen FlatBuffer nur anhand seiner Größe. Es sagt Ihnen, dass Ergebnisse eintreffen, nicht, was sie enthalten.

Gut zu wissen:

- Der Stream-Modus ist ein **Pegel**, kein Befehl, und der Stream kann vor dem Stream des Cam Driver gestartet werden: Die Ergebnisse treffen ein, sobald Bilder eintreffen. Siehe [Stream starten und stoppen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#running).
- 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-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#saving).

## Die Quelle ändern {#subscribing}

Ein Modul nimmt eine Quelle. Eine SPS oder ein anderer Client ändert sie im laufenden Betrieb, 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 auf `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-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#saving).

Die Methoden antworten mit einem Ergebnis, dessen Name vom Data Layer abhängt (siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results)):

| ctrlX Data Layer | LumiScan Keryx (PC) | 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 wurde geändert. |

Diese Methoden haben keinen `status-text`. Der Grund für eine Ablehnung wird in das Protokoll der Anwendung 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 Bilds {#result}

`control/subscribe/output/stream/result` enthält eine FlatBuffers-Tabelle vom Typ `stream_template_matches` (Dateikennung `HSTM`), auf dem Data Layer registriert als `types/hdvisionsystems/lumiscan-template-finder/stream_template_matches`. Ihr kompiliertes Schema wird als `bfbs/stream_template_matches.bfbs` installiert.

| Feld | Bedeutung |
| --- | --- |
| `lineage` | Woher das Ergebnis stammt, siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#lineage). |
| `result` | Die Treffer, als `hdv.template_match.Result`: dieselbe Tabelle, die `find-template` für dasselbe Bild auf `output/result` schreibt, beschrieben in [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html). `image_width` und `image_height` sind die Größe des Bilds. |

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

Ein Bild wird so dekodiert, wie `find-template` den Bildknoten dekodiert; es werden also dieselben Pixelformate akzeptiert, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html). Ein Bild des Streams und dasselbe Bild, über `input/input-image-address` gelesen, ergeben dieselben Treffer.

Ein Bild, das nicht durchsucht werden kann, ergibt kein Ergebnis. Es wird in `statistics/failed-frames` gezählt, und `control/subscribe/output/stream/last-failure` sagt warum, zum Beispiel:

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: template-name is empty
```

Die Gründe sind dieselben, die `find-template` in seinem `status-text` nennt: eine Eingabe, die es ablehnen würde, eine Vorlage, die es nicht lesen kann, eine Ausschnittsregion, die nicht in das Bild passt, eine Region, die kleiner als die Vorlage ist.

## 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 Bilds 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-template-finder/<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-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Bilds beim 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 genau: die Kamera über `producer`, das Bild über `run` und `sequence`. Um zu erfahren, von welcher Kamera ein Ergebnis stammt, lesen Sie den `producer` seines ersten Schritts. Eine Lücke in der `sequence` des Kameraschritts 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 Modulschritts in jedem Ergebnis identifizieren, womit die Ergebnisse erzeugt werden. Der Knoten zeigt den Hash als 16 Hexadezimalziffern; der Schritt enthält denselben Wert als Zahl. Der Hash umfasst:

- jede Eingabe von `find-template`, die die Suche liest, genau so, wie sie für das Bild gelesen wurde - alle außer `input/input-image-address`;
- die Vorlagendatei, anhand ihres Inhalts: Eine neue Vorlage, die unter dem alten Namen gespeichert wird, ist ein neuer Hash;
- 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 darin gefunden wird.

`setting/settings-hash` wird etwa alle halbe Sekunde aktualisiert, auch bei ausgeschaltetem Stream. 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": {
        "find-template/input/match-thresh": 0.9,
        "find-template/input/template-name": "screw",
        "find-template/template": {
            "file": "<configuration directory>/templates/screw.png",
            "fnv1a64": "<16 hex digits>"
        },
        "software.name": "lumiscan-template-finder",
        "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 benennen, von Hand. Jede Eingabe, die die Suche liest, wird gehasht; eine Änderung, die ein Ergebnis nicht verändert, kann den Hash 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 Stoppen 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` | Durchsuchte Bilder, jedes mit einem auf `control/subscribe/output/stream/result` veröffentlichten Ergebnis. |
| `skipped-frames` | Nie durchsuchte Bilder: von neueren aus der Warteschlange gedrängt, während ein Bild durchsucht wurde (siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#queue-size)), oder wartend, als die Quelle ersetzt oder entfernt wurde. |
| `failed-frames` | Bilder, die nicht durchsucht werden konnten. `control/subscribe/output/stream/last-failure` sagt, warum das letzte fehlgeschlagen ist, und das Protokoll nennt die Fehlschläge, höchstens eine Zeile alle 5 Sekunden. |
| `lost-frames` | Bilder, die verloren gingen, bevor sie ankamen, gezählt anhand von 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 Suchen gedauert haben, summiert, ohne die Zeit, die ein Bild auf `find-template` gewartet hat. Teilen Sie durch `processed-frames` für den Mittelwert. |

Bilder, die beim Stoppen 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 Element `stream` der Einstellungsdatei des Moduls gespeichert, `<module-id>.json` im Konfigurationsverzeichnis der Anwendung - die 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 `CreationFailed` (ctrlX: `DL_CREATION_FAILED`), 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 das Element `stream`; der Rest der Datei bleibt, wie er war. Das Modul legt die Datei an, wenn noch keine vorhanden ist - ein Modul, dessen Eingaben nie gespeichert wurden, hat keine. `system/save-module-inputs` wiederum behält das Element `stream` bei, wenn es die Datei neu schreibt; die Eingaben von `control/subscribe` werden nicht als Eingaben des Moduls gespeichert.

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

Das Element `stream`, neben den Eingaben von `find-template` (hier gekürzt):

```json
{
    "find-template": {
        "template-name": "screw"
    },
    "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 Modulschritts 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 auf `find-template/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 bei. |

`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` auf einer neuen Installation. Von Hand an der Datei vorgenommene Änderungen werden beim nächsten Start wirksam.
- Ein mit `system/create-module` angelegtes Modul startet mit ausgeschaltetem Stream, ohne Quelle, mit einer Warteschlangengröße von `1` und ausgeschaltetem `keep-latest-output`, unabhängig davon, was eine Datei seines Namens enthält. Was es von da an anwendet, wird in dieser Datei gespeichert.
- Damit ein Modul und sein Stream nach einem Neustart wieder da sind, 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-template-finder-de/1.1.0/lumiscan-template-finder/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.
- Das Element `subscriptions` früherer Versionen wird nicht mehr gelesen, und das Modul protokolliert, dass es 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 durchsucht 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, drängt das älteste von ihnen hinaus, 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 durchsucht das neueste Bild. Es fällt nie zurück; ist die Suche langsamer als die Kamera, überspringt es Bilder. |
| Mehr als 1 | Kurze Bildfolgen werden vollständig durchsucht, und weniger Bilder werden übersprungen. Ist die Suche über längere Zeit langsamer als die Kamera, fällt das Modul zurück: Es durchsucht Bilder, die bis zu so viele Suchen 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 auf `find-template/output/result`, so wie `find-template/execute` es schreibt, sobald das Ergebnis auf `control/subscribe/output/stream/result` veröffentlicht ist. Ein Client, der `find-template/output/result` liest, hat dann das Ergebnis des neuesten Bilds, ohne den Stream zu abonnieren. `status-code` und `status-text` werden nicht geschrieben: Sie behalten, was der letzte Aufruf von `find-template` dort hinterlassen hat. Es kostet eine Kopie jedes Ergebnisses. Standardmäßig aus.

## find-template bei laufendem Stream {#while-streaming}

Der Stream und `find-template` verwenden dieselben Eingaben, und sie laufen auf einem Modul nie gleichzeitig:

- Ein Bild, das eintrifft, während `find-template` läuft, wartet, bis die Methode abgeschlossen ist. Es wird verzögert, nicht als fehlgeschlagen gewertet.
- Ein Aufruf von `find-template/execute`, während ein Bild durchsucht wird, antwortet mit belegt: `output/status-code` ist `-1`, der Schreibvorgang antwortet mit `TooManyOperations` (ctrlX: `DL_TOO_MANY_OPERATIONS`), 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-template-finder-de/1.1.0/lumiscan-template-finder/execute-a-method.html)). Bei einer streamenden Kamera passiert das häufig. 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 durchsucht wird. Stoppen Sie zuerst den Stream. Das Entfernen eines Moduls stoppt seinen Stream.
- `system/create-template` hat eine eigene Sperre und wird vom Stream nicht aufgehalten.

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

## Einschränkungen {#limitations}

- Der Stream wurde nur unter Windows mit LumiScan Keryx und simulierten Bildern getestet. Er wurde nicht unter Linux - auf ctrlX OS oder Ubuntu -, 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 werden beim nächsten Start der Anwendung wirksam.
- Der Hash umfasst jede Eingabe, die die Suche liest. Er ändert sich bei manchen Änderungen, die ein Ergebnis nicht verändern.

# Die Suche abstimmen – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html

Alle diese Werte sind Eingaben von `find-template`. Die Standardwerte suchen die Vorlage in ihrer ursprünglichen Größe und Ausrichtung; das ist die schnellste Konfiguration und der richtige Ausgangspunkt.

## Suchbereich

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/scale/min-scale` | double | `1.0` | Kleinster Skalierungsfaktor der Vorlage. Muss größer als 0 sein |
| `input/scale/max-scale` | double | `1.0` | Größter Skalierungsfaktor der Vorlage |
| `input/scale/step-scale` | double | `1.0` | Schrittweite zwischen den durchsuchten Skalierungen |
| `input/rotation/min-rot` | double | `0.0` | Kleinste Drehung in Grad, 0 bis 360 |
| `input/rotation/max-rot` | double | `0.0` | Größte Drehung in Grad, 0 bis 360 |
| `input/rotation/step-rot` | double | `1.0` | Schrittweite zwischen den durchsuchten Drehungen. Muss größer als 0 sein |

Ist das Minimum gleich dem Maximum, wird nur dieser eine Wert durchsucht und die Schrittweite ignoriert.

> [!IMPORTANT]
> Die Arbeit ist **ein Durchlauf pro Kombination**. Die Suche über 5 Skalierungen und 36 Drehungen sind 180 Durchläufe über das Bild, nicht 41. Erweitern Sie einen Bereich nur so weit, wie die Teile tatsächlich variieren, und bevorzugen Sie eine grobe Schrittweite: Eine Drehungsschrittweite von 5 Grad lokalisiert ein Teil meist gut genug für eine anschließende Messung.

## Matching

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/match-thresh` | double | `0.9` | Kleinster akzeptierter Score, 0 bis 1 |
| `input/match-mode` | string | `TM_SQDIFF_NORMED` | Matching-Algorithmus |
| `input/use-grayscale` | bool | `true` | Matching auf Graustufen, wenn die Bilder farbig sind |

`match-mode` akzeptiert `TM_SQDIFF`, `TM_SQDIFF_NORMED`, `TM_CCORR`, `TM_CCORR_NORMED`, `TM_CCOEFF` und `TM_CCOEFF_NORMED`. Scores verschiedener Modi sind nicht vergleichbar; deshalb ist der verwendete Modus im Ergebnis enthalten.

`use-grayscale` macht das Matching etwa dreimal schneller, weil nicht jeder Farbkanal einzeln korreliert wird, und kostet in den meisten industriellen Szenen kaum Genauigkeit. Schalten Sie es aus, wenn die Farbe das Teil unterscheidet.

## Die Konfidenz verstehen

Die Konfidenz ist **kein** absolutes Maß der Ähnlichkeit. Die Score-Karte wird für jeden Skalierungs-/Drehungsschritt einmal neu skaliert, was zwei Konsequenzen hat, die man kennen sollte:

- Die beste Stelle **jedes** Schritts erreicht eine Konfidenz nahe 1, auch wenn die Skalierung dieses Schritts zu nichts im Bild passt.
- `match-thresh` wirkt daher **pro Schritt** statt global, sobald Sie einen Bereich durchsuchen.

Eine Suche mit einer einzigen Skalierung und Drehung verhält sich wie erwartet. Eine weite Suche kann neben dem echten Treffer schwache Treffer an unzusammenhängenden Stellen melden. Der echte Treffer ist weiterhin der Eintrag mit der höchsten Konfidenz, an Index 0.

Wenn Sie Scheintreffer sehen, erhöhen Sie `match-thresh` oder verkleinern Sie den Bereich.

Die Anwendung entfernt außerdem Duplikate: Ohne das würde eine Suche über 10 Schritte dasselbe Teil bis zu 10-mal melden. Entfernt werden nur Wiederholungen an **derselben Stelle**; deshalb kann ein schwacher Treffer an anderer Stelle trotzdem erscheinen.

## Vorverarbeitung

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/preprocess/blur-sigma-x` | double | `1.0` | Stärke der Gauß-Unschärfe in X. 0 oder weniger schaltet die Unschärfe aus |
| `input/preprocess/blur-sigma-y` | double | `0.0` | Stärke der Unschärfe in Y. 0 bedeutet dieselbe wie in X |
| `input/preprocess/blur-kernel-size-x` | uint32 | `0` | Breite des Unschärfe-Kernels. 0 leitet sie aus der Stärke der Unschärfe ab; sonst eine ungerade Zahl |
| `input/preprocess/blur-kernel-size-y` | uint32 | `0` | Höhe des Unschärfe-Kernels. 0 leitet sie aus der Stärke der Unschärfe ab; sonst eine ungerade Zahl |
| `input/preprocess/bin-size` | int32 | `1` | Verkleinert beide Bilder vor dem Matching um diesen Faktor. 1 schaltet es aus |

Die Unschärfe unterdrückt Sensorrauschen, auf Kosten etwas Positionsgenauigkeit. Der Standardwert ist eine leichte Unschärfe, die zu den meisten Kameras passt.

Binning ist die wirksamste Stellschraube für die Geschwindigkeit: Der Matching-Aufwand sinkt mit dem Quadrat des Faktors; eine Bin-Größe von 2 ist also etwa viermal schneller. Die Grenze ist die Vorlage - sobald ein unterscheidendes Merkmal auf wenige Pixel schrumpft, ist es nicht mehr unterscheidbar. Kleine oder dünne Vorlagen sollten bei 1 bleiben.

## Eine praktische Reihenfolge

1. Beginnen Sie mit den Standardwerten und suchen Sie nach einer Vorlage, die aus demselben Aufbau ausgeschnitten wurde. Bestätigen Sie, dass sie gefunden wird.
2. Wenn die Teile in der Ausrichtung variieren, erweitern Sie den Drehungsbereich mit einer groben Schrittweite.
3. Wenn sie im Abstand variieren, erweitern Sie den Skalierungsbereich.
4. Wenn es zu langsam ist, erhöhen Sie `bin-size` auf 2 und prüfen Sie, ob die Konfidenz noch akzeptabel ist.
5. Wenn Scheintreffer erscheinen, erhöhen Sie `match-thresh`.

# Speicherung der Vorlagen – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html

Vorlagen sind gewöhnliche PNG-Dateien im Konfigurationsverzeichnis der Anwendung. Sie können sie mit normalen Werkzeugen ansehen, kopieren und sichern, und eine anderswo vorbereitete Vorlage kann einfach hochgeladen (ctrlX OS) oder hineinkopiert werden (PC).

## Wo sie liegen

Das Konfigurationsverzeichnis und darin ein Ordner `templates` werden beim ersten Start der Anwendung angelegt, sodass es auf einer ganz neuen Installation einen Ort zum Hochladen oder Kopieren gibt. Wo es liegt, hängt von der Plattform ab.

### Auf ctrlX OS

Auf einem ctrlX-Gerät ist das Konfigurationsverzeichnis Teil der **aktiven Solution**:

```
/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder
```

Weil es zur Solution gehört, werden Vorlagen beim Export der Solution mitgenommen und mit ihr auf einem anderen Gerät wiederhergestellt.

### Auf einem PC

Unter Windows ist das Konfigurationsverzeichnis `%APP_RESOURCE_DIR%\etc\lumiscan-template-finder`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder`.

## Aufbau

```
<configuration directory>/
├── lumiscan-template-finder.json   module list, chosen template folder, log level
├── module-1.json                   saved settings of one module
└── templates/                      default template folder
    ├── screw.png
    └── bracket.png
```

**Ein Ordner dient der gesamten Anwendung**, nicht einer pro Modul: Jedes Modul durchsucht ihn, und `create-template` schreibt hinein; eine von einem Modul erstellte Vorlage ist also sofort für alle nutzbar.

`module-1.json` wird von `system/save-module-inputs` geschrieben - siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html).

## Log-Level

`lumiscan-template-finder.json` enthält auch, wie viel die Anwendung protokolliert, im selben Block `system`, den die anderen LumiScan-Anwendungen verwenden:

```json
{
    "system": {
        "logLevel": "TRACE"
    }
}
```

Akzeptiert werden `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` und `OFF`, von den meisten Details bis zu keinen. `TRACE` ist der Wert, den Sie setzen, bevor Sie ein Problem für einen Support-Bericht reproduzieren.

Der Level wird **einmal, beim Start** gelesen; starten Sie die Anwendung nach einer Änderung also neu. Fügen Sie den Block von Hand hinzu: Die Anwendung schreibt in diese Datei nur `template-dir` und `modules` und lässt alles andere darin unverändert.

Der Schlüssel ist optional. Ohne ihn protokolliert die Anwendung auf ihrem eingebauten Level `DEBUG`, und ein Wert, der keiner der obigen Namen ist, wird im Protokoll gemeldet und ändert nichts - ein Tippfehler hier kann die Anwendung nie zum Schweigen bringen.

## Den Ordner wählen

```
system/template-dir                          read-only, the folder in use
system/templates                             read-only, what is in it
system/set-template-dir/execute              change it
system/set-template-dir/input/template-dir   the folder to change to
```

`template-dir` und `templates` sind **schreibgeschützte Ausgaben** von `set-template-dir`, sodass die Liste nie von dem Ordner abweichen kann, aus dem sie stammt. Um den Ordner zu wechseln, schreiben Sie `set-template-dir/input/template-dir`, führen dann die Methode aus und prüfen, dass `set-template-dir/output/status-code` `1` ist.

Der Ordner muss bereits vorhanden sein. Er wird **nicht** für Sie angelegt: Der Standardordner `templates` wird beim Start angelegt; ein fehlender Ordner bedeutet also, dass der Name falsch ist, und stillschweigend einen leeren anzulegen würde den Fehler verbergen. Die Wahl wird gespeichert und beim nächsten Start wiederhergestellt.

Wird der Aufruf abgelehnt, ändert sich nichts - die Anwendung verwendet weiter den bisherigen Ordner.

### system/templates

Jede Vorlage im Ordner, **ohne die Erweiterung `.png`**, sortiert:

```
["bracket", "screw"]
```

Ein Eintrag kann direkt in `find-template/input/template-name` übernommen werden. Die Liste wird beim Start, nach einem erfolgreichen `set-template-dir` und beim Speichern einer neuen Vorlage durch `create-template` aktualisiert.

> [!NOTE]
> Sie wird **nicht** aktualisiert, wenn eine Datei auf anderem Weg ankommt, etwa durch ein Hochladen über die ctrlX-Weboberfläche (ctrlX OS) oder eine in den Ordner kopierte Datei (PC). Führen Sie `set-template-dir` erneut mit demselben Ordner aus, um eine solche Datei zu übernehmen.
>
> Nur Dateien, die auf `.png` in Kleinbuchstaben enden, werden aufgeführt. `SCREW.PNG` wird ignoriert.

## Vorlagen auf das Gerät bringen

- **Aus einem Live-Bild:** [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html) schreibt die Datei direkt. Keine Dateiübertragung nötig.
- **Über die ctrlX-Weboberfläche (ctrlX OS):** Der Datenordner der Anwendung ist durchsuchbar, sodass ein vorbereitetes PNG in `templates` hochgeladen werden kann.
- **Mit der Solution (ctrlX OS):** Vorlagen, die in der Konfiguration der aktiven Solution gespeichert sind, wandern mit ihr auf ein anderes Gerät.
- **Durch Kopieren (PC):** Ein vorbereitetes PNG kann in `templates` im Konfigurationsverzeichnis kopiert werden.

Eine im laufenden Betrieb hinzugefügte Vorlage wird bei der nächsten Suche übernommen - die Datei wird jedes Mal gelesen, nicht beim Start zwischengespeichert; ein Neustart ist also nicht nötig.

## Dateiformat

- PNG, 8-Bit-RGB. Erstellte Vorlagen werden immer so geschrieben, unabhängig vom Pixelformat der Kamera.
- Ein Graustufen-PNG funktioniert ebenfalls.
- `.png` wird angehängt, wenn der Name keine Erweiterung hat; `screw` und `screw.png` bezeichnen also dieselbe Datei.

## Pfadregeln

Ordner- und Dateinamen werden immer **relativ zum Konfigurationsverzeichnis** interpretiert. Zwei Dinge werden mit Statuscode `-2` abgelehnt:

- ein absoluter Pfad, etwa `/tmp/templates`
- ein Pfad, der aus dem Konfigurationsverzeichnis hinausführt, etwa `../../etc`

Die Anwendung kann also immer nur innerhalb ihres eigenen Konfigurationsverzeichnisses lesen und schreiben. Ein Pfad, der darin bleibt, ist in Ordnung, auch wenn er `..` enthält.

## Fehlerbehebung

Probleme mit dem Vorlagenordner und den Vorlagendateien sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html) beschrieben:

- [Statuscode `-4` (Quelle nicht gefunden)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-4) - nennt ein Verzeichnis oder eine Datei, oder eine Datei ist da, wird aber nicht gefunden
- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-2) - ein absoluter Pfad oder einer, der aus dem Konfigurationsverzeichnis hinausführt
- [Statuscode `-6` (Schreiben fehlgeschlagen)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-status-minus-6)
- [Die Vorlagendatei liegt auf dem Gerät, fehlt aber in `system/templates`](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-template-not-listed)

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

Auf einem PC schreibt der Template Finder ein Beispiel seiner Einstellungen in einen Ordner Ihrer Wahl und beendet sich, ohne zu starten. Zum Beispiel unter Windows:

```shell
lumiscan-templ-find --generate-settings C:\work\template-finder-settings
```

Ohne Ordner (`-g` allein) schreibt er in den aktuellen Ordner. Das Beispiel ist die Einstellungsdatei der Anwendung `lumiscan-template-finder.json`, die das Modul `module-1` benennt, und daneben die Moduldatei `module-1.json`: jede Eingabe von `find-template` mit ihrem Standardwert, außer der Bildadresse, die auf `camera1` des Cam Driver zeigt. Daneben, in `schemas/`, liegen die Schemas, die die beiden Dateien in `"$schema"` nennen: `lumiscan-template-finder.schema.json`, `lumiscan-template-finder-module.schema.json` und `stream.schema.json` für den Abschnitt `stream` einer Moduldatei. Sie beschreiben jeden Schlüssel, den der Template Finder liest - jede Eingabe von `find-template` 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 bei, die es speichert. Vorhandene Dateien werden nie überschrieben: Liegt eine von ihnen bereits im Ordner, wird nichts geschrieben, und der Template Finder nennt welche.

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

# Modulverwaltung – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html

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

```
hdvisionsystems/lumiscan-template-finder/<module-id>/find-template/...
```

Das Erstellen einer Vorlage ist **nicht** modulbezogen: Es schreibt in das eine Verzeichnis, das sich alle Module teilen, und liegt deshalb auf dem Systemknoten als `system/create-template`. Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).

Module können im laufenden Betrieb angelegt und entfernt werden. Eine neue 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-template-finder/system/
```

## Knoten

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `modules` | string array | Die derzeit vorhandenen Module |
| `create-template/execute` | Methode | Schneidet eine Vorlage aus einem Live-Bild aus und speichert sie in `template-dir`, zur Verwendung durch jedes Modul. Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html) |
| `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 nicht bereits 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, sodass 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`.

## 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, dass `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.

Das Entfernen eines Moduls 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 Standardwerten der Eingaben, 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 solange die Liste nicht 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, dass `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. Die Bild-Stream-Einstellungen eines Moduls werden in derselben Datei gespeichert, von den eigenen Methoden des Streams - siehe [In der Einstellungsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#saving).

Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen, sodass eine ältere Konfiguration die Anwendung nie am Starten hindert.

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

Die Ebene `<module-id>` ist immer vorhanden, sodass sich die Adressen nicht ändern, wenn ein zweites Modul hinzukommt: Ein heute für `module-1` geschriebenes Programm funktioniert weiter. Das entspricht auch der Pfadkonvention, die die anderen LumiScan-Anwendungen dokumentieren, siehe [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html). Wie sich die Module der Finder von denen des Cam Driver, von AI Object Matching und Calibration unterscheiden, fasst [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html#registry-apps) zusammen.

## Was Module gemeinsam haben

Module sind in allem unabhängig außer bei den Vorlagen. `system/template-dir` benennt ein Verzeichnis für die gesamte Anwendung, `system/create-template` schreibt hinein, und jedes Modul durchsucht es; eine Vorlage muss also nur einmal erstellt werden. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

# Data-Layer-Referenz – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html

Vollständige Liste der Knoten. Alle Pfade beginnen mit:

```
hdvisionsystems/lumiscan-template-finder/
```

## Data Layer {#data-layer}

LumiScan Template Finder bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-template-finder` an.

Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) nutzt LumiScan Template Finder 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 Template Finder [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Template Finder 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.

## Adressmuster

```
hdvisionsystems/lumiscan-template-finder/
├── system/                              application-wide management
│   ├── modules
│   ├── template-dir                     the one directory templates live in
│   ├── templates                        what is in it
│   ├── set-template-dir/
│   ├── create-template/                 application-wide, not per module
│   ├── create-module/
│   ├── remove-module/
│   ├── save-current-modules/
│   ├── save-module-inputs/
│   └── meta/subscription-schema         what the stream's source must hold
└── <module-id>/                         one per configured instance, e.g. module-1
    ├── find-template/
    │   ├── execute
    │   ├── input/...
    │   └── output/{result, status-code, status-text}
    ├── control/subscribe/               the image stream (experimental)
    │   ├── execute
    │   ├── input/{enable, address, tag, queue-size, keep-latest-output}
    │   └── output/stream/...
    ├── control/unsubscribe/{execute, input/address}
    └── setting/{stream, settings-hash}
```

Jede Operation hat `execute`, `output/status-code` und `output/status-text`. Alles Weitere unter `output/` ist nur dort vorhanden, wo die Operation mehr zu melden hat.

> [!NOTE]
> Eine neue Installation stellt ein Modul bereit, `module-1`; weitere können zur Laufzeit angelegt werden. Auf ctrlX OS deckt eine Lizenz zehn Module ab. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html).

## system

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `system/modules` | string array | Die derzeit vorhandenen Module |
| `system/template-dir` | string | Verzeichnis, aus dem jedes Modul Vorlagen liest und in das sie geschrieben werden, relativ zum Konfigurationsverzeichnis. Schreibgeschützt - ändern Sie es mit `set-template-dir` |
| `system/templates` | string array | In diesem Verzeichnis verfügbare Vorlagen, ohne die Erweiterung `.png`. Schreibgeschützt |
| `system/set-template-dir/execute` | Methode | Richtet die Anwendung auf ein anderes Vorlagenverzeichnis |
| `system/set-template-dir/input/template-dir` | string | Verzeichnis, zu dem gewechselt wird. Es muss bereits vorhanden sein |
| `system/create-template/execute` | Methode | Schneidet eine Vorlage aus einem Live-Bild aus und speichert sie in `template-dir`. Gilt für die gesamte Anwendung: Die Vorlage ist für jedes Modul nutzbar. Ihre Eingaben und Ausgaben sind unter [system/create-template](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html#system_create_template) aufgeführt |
| `system/create-module/execute` | Methode | Legt ein Modul und seinen Knoten-Teilbaum an |
| `system/create-module/input/module-id` | string | Name des anzulegenden Moduls |
| `system/remove-module/execute` | Methode | Entfernt ein Modul und seinen Knoten-Teilbaum |
| `system/remove-module/input/module-id` | string | Name des zu entfernenden Moduls |
| `system/save-current-modules/execute` | Methode | Speichert die Modulliste dauerhaft, sodass dieselben Module nach einem Neustart wieder da sind |
| `system/save-module-inputs/execute` | Methode | Speichert die Eingaben eines Moduls dauerhaft |
| `system/save-module-inputs/input/module-id` | string | Modul, dessen Eingaben gespeichert werden sollen |
| `system/meta/subscription-schema` | string | 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 gleich. Schreibgeschützt. Experimentell |

## \<module-id>/find-template

### Eingaben

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/input-image-address` | string | *(leer)* | Adresse des zu durchsuchenden Bildknotens |
| `input/template-name` | string | *(leer)* | Gesuchte Vorlage, wie auf `system/templates` aufgeführt. `.png` wird angehängt, wenn keine Erweiterung angegeben ist |
| `input/crop/startX` | uint16 | `0` | Linker Rand der zu durchsuchenden Region, Pixel |
| `input/crop/startY` | uint16 | `0` | Oberer Rand der zu durchsuchenden Region, Pixel |
| `input/crop/width` | uint16 | `0` | Breite der Region. `0` reicht bis zum rechten Rand |
| `input/crop/height` | uint16 | `0` | Höhe der Region. `0` reicht bis zum unteren Rand |
| `input/result-coordinate` | string | `IMAGE` | `IMAGE` oder `CROP`: auf welches Bild sich die Positionen im Ergebnis beziehen |
| `input/scale/min-scale` | double | `1.0` | Kleinster Skalierungsfaktor |
| `input/scale/max-scale` | double | `1.0` | Größter Skalierungsfaktor |
| `input/scale/step-scale` | double | `1.0` | Schrittweite zwischen den Skalierungen |
| `input/rotation/min-rot` | double | `0.0` | Kleinste Drehung, Grad |
| `input/rotation/max-rot` | double | `0.0` | Größte Drehung, Grad |
| `input/rotation/step-rot` | double | `1.0` | Schrittweite zwischen den Drehungen, Grad |
| `input/match-thresh` | double | `0.9` | Kleinster akzeptierter Score, 0-1 |
| `input/match-mode` | string | `TM_SQDIFF_NORMED` | Matching-Algorithmus |
| `input/use-grayscale` | bool | `true` | Matching auf Graustufen |
| `input/preprocess/blur-sigma-x` | double | `1.0` | Stärke der Unschärfe in X; 0 oder weniger schaltet sie aus |
| `input/preprocess/blur-sigma-y` | double | `0.0` | Stärke der Unschärfe in Y; 0 bedeutet dieselbe wie in X |
| `input/preprocess/blur-kernel-size-x` | uint32 | `0` | Breite des Unschärfe-Kernels; 0 leitet sie aus der Stärke ab |
| `input/preprocess/blur-kernel-size-y` | uint32 | `0` | Höhe des Unschärfe-Kernels; 0 leitet sie aus der Stärke ab |
| `input/preprocess/bin-size` | int32 | `1` | Faktor der Verkleinerung; 1 schaltet sie aus |

### Ausgaben

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `output/result` | flatbuffer | Treffer, nach Konfidenz sortiert |
| `output/status-code` | int16 | Ausführungsstatus |
| `output/status-text` | string | Ergebnis in Worten |

## \<module-id> Bild-Stream (experimentell) {#module_stream}

Die folgenden Adressen sind relativ zu `<module-id>/`, neben `find-template/`. Der Stream durchsucht jedes Bild mit den Eingaben von `find-template`, alle außer `input/input-image-address`. Siehe [Vorlagen in einem Bild-Stream finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

### Eingaben

| Knoten | 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 durchsucht wird, 1-64 |
| `control/subscribe/input/keep-latest-output` | bool | wie angewendet | `true` schreibt jedes Stream-Ergebnis zusätzlich auf `find-template/output/result` |
| `control/unsubscribe/input/address` | string | (leer) | Die zu entfernende Quelle, wie `setting/stream/address` sie zeigt |

### Methoden

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `control/subscribe/execute` | Methode | Prüft die Eingaben von `control/subscribe` gemeinsam, speichert sie in `<module-id>.json` als `stream` und wendet sie dann an. Nur eine Eingabe zu schreiben ändert nichts |
| `control/unsubscribe/execute` | Methode | Entfernt die von `control/unsubscribe/input/address` genannte Quelle, was den Stream-Modus beendet; das Tag bleibt. Wird wie ein Subscribe in `<module-id>.json` gespeichert |

### Einstellungen und Ausgaben

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `setting/stream/{enable, address, tag, queue-size, keep-latest-output}` | wie die Eingaben | 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 Hexadezimalziffern. Schreibgeschützt |
| `control/subscribe/output/stream/active` | bool | `true`, solange der Stream läuft |
| `control/subscribe/output/stream/result` | flatbuffer | Ein `stream_template_matches` pro durchsuchtem Bild. Abonnieren Sie den Knoten, um jedes zu erhalten |
| `control/subscribe/output/stream/last-failure` | string | Warum das letzte Bild, das nicht durchsucht werden konnte, fehlgeschlagen ist, mit der Quelle anhand ihrer Adresse |
| `control/subscribe/output/stream/statistics/elapsed-ms` | uint64 | Millisekunden seit dem Start des Streams |
| `control/subscribe/output/stream/statistics/received-frames` | uint64 | Bilder, die das Abonnement geliefert hat |
| `control/subscribe/output/stream/statistics/processed-frames` | uint64 | Durchsuchte Bilder, jedes mit einem Ergebnis |
| `control/subscribe/output/stream/statistics/skipped-frames` | uint64 | Bilder, die aus der Warteschlange gedrängt wurden oder warteten, als die Quelle ersetzt oder entfernt wurde |
| `control/subscribe/output/stream/statistics/failed-frames` | uint64 | Bilder, die nicht durchsucht werden konnten |
| `control/subscribe/output/stream/statistics/lost-frames` | uint64 | Bilder, die verloren gingen, bevor sie ankamen |
| `control/subscribe/output/stream/statistics/processing-us` | uint64 | Suchzeit aller durchsuchten 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 für den Stream-Modus ohne Adresse oder mit einer Warteschlangengröße außerhalb von 1-64 abgelehnt, `control/unsubscribe/execute` für eine Adresse, die nicht die Quelle ist (`Rejected`, ctrlX: `DL_INVALID_VALUE`). Kann `<module-id>.json` nicht geschrieben werden, antworten beide mit `CreationFailed` (ctrlX: `DL_CREATION_FAILED`) und ändern nichts. Die Stream-Knoten sind in jedem Konsumenten gleich, siehe [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#consumer).

## system/create-template {#system_create_template}

### Eingaben

| Knoten | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/input-image-address` | string | *(leer)* | Adresse des Bildknotens, aus dem ausgeschnitten wird |
| `input/crop/startX` | int32 | `0` | Linker Rand der Region, Pixel |
| `input/crop/startY` | int32 | `0` | Oberer Rand der Region, Pixel |
| `input/crop/width` | int32 | `0` | Breite der Region, Pixel |
| `input/crop/height` | int32 | `0` | Höhe der Region, Pixel |
| `input/template-name` | string | *(leer)* | Name, unter dem in `system/template-dir` gespeichert wird. Verwenden Sie Kleinbuchstaben: Nur `.png`-Dateien in Kleinbuchstaben werden aufgeführt |

### Ausgaben

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `output/template-path` | string | Pfad der geschriebenen Datei, relativ zum Konfigurationsverzeichnis |
| `output/status-code` | int16 | Ausführungsstatus |
| `output/status-text` | string | Ergebnis in Worten |

## Ergebnis-FlatBuffer

`output/result` ist ein `hdv.template_match.Result`:

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `matches` | Array aus `Match` | Ein Eintrag pro Vorkommen, nach Konfidenz sortiert |
| `best_index` | ulong | Index des besten Treffers; immer 0 |
| `best_score` | float | Konfidenz des besten Treffers; 0.0, wenn keiner |
| `template_name` | string | Verwendete Vorlage |
| `match_mode` | string | Verwendeter Algorithmus |
| `match_thresh` | float | Angewendeter Schwellwert |
| `image_width` | uint | Breite des durchsuchten Bilds |
| `image_height` | uint | Höhe des durchsuchten Bilds |
| `timestamp` | ulong | Mikrosekunden seit der Epoche |

`Match`:

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `oriented_bounding_box` | struct | `center_x`, `center_y`, `width`, `height` in Pixeln; `angle` in Grad |
| `confidence` | float | Score, 0-1 |
| `scale` | float | Skalierungsfaktor dieses Treffers |
| `rotation` | float | Drehung dieses Treffers, Grad |

`control/subscribe/output/stream/result` ist ein `hdv.stream.StreamTemplateMatches` (`stream_template_matches`, registriert als `types/hdvisionsystems/lumiscan-template-finder/stream_template_matches`): `lineage`, woher das Bild kam, und `result`, das obige `hdv.template_match.Result`.

## Erwarteter Bildknoten unter `input-image-address`

Die Adresse muss einen Bildknoten einer **anderen** Anwendung auf demselben Gerät benennen - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC -, der Folgendes bereitstellt:

| Kindknoten | Typ | Beschreibung |
| --- | --- | --- |
| `data` | Array aus uint8 | Rohe Pixeldaten |
| `width` | uint64 | Breite in Pixeln |
| `height` | uint64 | Höhe in Pixeln |
| `pixel-type` | string | Name des GenICam-Pixelformats |

Eine Adresse innerhalb dieser Anwendung wird mit Statuscode `-2` abgelehnt.

## Statuscodes

Die vollständige Tabelle steht in [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html). Negativ ist immer ein Fehler; `0` bedeutet noch nicht ausgeführt; positiv bedeutet Erfolg. Das sind die eigenen Codes der Finder, nicht der Modulstatus der anderen LumiScan-Apps, siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

# FAQ – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/faq.html

Kurze Antworten auf häufige Fragen zu LumiScan Template Finder. Jeder Eintrag verweist auf die Seite mit den Details.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-pixel-formats`). Probleme, Fehlermeldungen und Statuscodes sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html) beschrieben.

## Voraussetzungen und Einrichtung

### Auf welchen Plattformen läuft der Template Finder, und welchen Data Layer verwendet er? {#faq-platforms}

- **Antwort:** Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) verwendet er den ctrlX Data Layer; auf einem PC mit Windows 11 oder Ubuntu 24.04 verwendet er LumiScan Keryx, den Data Layer von HD Vision Systems für PCs. Die Knotenadressen, Typen und die Art, wie die Methoden aufgerufen werden, sind auf beiden gleich; ein Programm, das für den einen geschrieben wurde, funktioniert auch mit dem anderen. Nur die Namen der Ergebnisse eines Methodenaufrufs unterscheiden sich, zum Beispiel `DL_TOO_MANY_OPERATIONS` auf dem ctrlX Data Layer und `TooManyOperations` bei LumiScan Keryx.
- **Mehr:** [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html), [ctrlX Data Layer und LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html)

### Welche Bildquelle benötigt der Template Finder? {#faq-image-source}

- **Antwort:** Die Anwendung spricht nicht selbst mit einer Kamera. Sie liest den Bildknoten einer anderen Anwendung, die auf **demselben Gerät** läuft - derselben ctrlX CORE oder demselben ctrlX IPC oder demselben PC (ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt), normalerweise LumiScan Cam Driver, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Jede Anwendung ist geeignet, deren Bildknoten `data` (rohe, unkomprimierte uint8-Pixeldaten), `width`, `height` und `pixel-type` (Name des GenICam-Pixelformats) bereitstellt. Eine Adresse innerhalb des Template Finder selbst wird mit Statuscode `-2` abgelehnt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html), [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/datalayer-reference.html)

### Welche Pixelformate werden unterstützt? {#faq-pixel-formats}

- **Antwort:** `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` und `BayerRG12`. Bayer-Bilder werden vor dem Matching in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert, sodass Vorlagen aus einem Format auch in Bildern eines anderen Formats gefunden werden. Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html)

## Vorlagen

### Wie erstelle ich eine Vorlage aus einem Live-Kamerabild? {#faq-create-template}

- **Antwort:** Verwenden Sie `system/create-template`. Die Methode gilt für die gesamte Anwendung: Sie schneidet eine Region aus dem aktuellen Bild aus und speichert sie als PNG, das jedes Modul verwenden kann:
  - Stellen Sie sicher, dass die Kameraanwendung ein Bild aufgenommen hat.
  - Setzen Sie `system/create-template/input/input-image-address`, die vier Werte unter `input/crop/` (`width` und `height` müssen größer als 0 sein) und `input/template-name`. Verwenden Sie einen Namen in Kleinbuchstaben; `.png` wird angehängt, wenn Sie keine Erweiterung angeben.
  - Schreiben Sie auf `system/create-template/execute` und lesen Sie `output/status-code`. Bei `1` benennt `output/template-path` die Datei, zum Beispiel `templates/screw.png`.
  - Bei `-5` passt die Region nicht in das Bild; `output/status-text` nennt die tatsächliche Bildgröße.
  - Die Datei wird als 8-Bit-RGB-PNG geschrieben, unabhängig vom Pixelformat der Kamera. Eine vorhandene Datei mit demselben Namen wird ohne Warnung überschrieben.
- **Mehr:** [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html), [Anleitung: Ein Teil in einem Kamerabild finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/how-tos/match-a-part-from-a-camera-image.html)

### Wo werden Vorlagen gespeichert, und kann ich eine auf einem PC vorbereitete Vorlage hochladen? {#faq-template-storage}

- **Antwort:** Vorlagen sind PNG-Dateien im Ordner `templates` des Konfigurationsverzeichnisses der Anwendung, der beim ersten Start angelegt wird. Eine von Hand hinzugefügte Vorlage wird bei der nächsten Suche gelesen, ohne Neustart.
  - Auf ctrlX OS ist das Verzeichnis Teil der aktiven Solution (`/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder`), sodass Vorlagen mit der Solution exportiert und wiederhergestellt werden. Ein vorbereitetes PNG (8-Bit-RGB oder Graustufen) kann über die ctrlX-Weboberfläche dorthin hochgeladen werden.
  - Auf einem PC wird ein vorbereitetes PNG in den Ordner kopiert. Unter Windows ist das Verzeichnis `%APP_RESOURCE_DIR%\etc\lumiscan-template-finder`, oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder`.
  - Um einen anderen Ordner zu verwenden, schreiben Sie `system/set-template-dir/input/template-dir`, führen Sie `system/set-template-dir` aus und prüfen Sie, dass der Statuscode `1` ist. Der Ordner muss bereits vorhanden sein; ein absoluter Pfad oder ein Pfad, der aus dem Konfigurationsverzeichnis hinausführt, wird mit `-2` abgelehnt.
- **Mehr:** [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html)

## Suchen und Abstimmen

### Wie führe ich eine Suche aus und lese das Ergebnis? {#faq-read-result}

- **Antwort:** Setzen Sie `find-template/input/input-image-address` und `find-template/input/template-name` (wie auf `system/templates` aufgeführt), schreiben Sie auf `find-template/execute` und lesen Sie `find-template/output/status-code`. Der Schreibvorgang blockiert und kehrt zurück, wenn die Suche abgeschlossen ist. Bei `1` lesen Sie `output/result`: `matches` ist nach Konfidenz sortiert, sodass `matches[0]` und `best_score` den besten Treffer liefern. Jeder Treffer hat eine `oriented_bounding_box` (`center_x`, `center_y`, `width`, `height` in Pixeln, `angle` in Grad), `confidence`, `scale` und `rotation`. Eine leere Liste `matches` mit Status `1` ist ein normales Ergebnis: Das Teil wurde nicht gefunden.
- **Mehr:** [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html)

### Wie kann ich die Suche beschleunigen? {#faq-search-too-slow}

- **Antwort:**
  - Suchen Sie nur in einem so großen Skalierungs- und Drehungsbereich, wie die Teile tatsächlich variieren, mit einer groben Schrittweite.
  - Erhöhen Sie `input/preprocess/bin-size` auf `2` (etwa viermal schneller) und prüfen Sie, ob die Konfidenz noch akzeptabel ist. Kleine oder dünne Vorlagen sollten bei `1` bleiben.
  - Belassen Sie `input/use-grayscale` auf `true` (etwa dreimal schneller als das Matching jedes einzelnen Farbkanals); schalten Sie es nur aus, wenn die Farbe das Teil unterscheidet.
  - Beschränken Sie die Suche mit `input/crop/` auf eine Region.
- **Mehr:** [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html), [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html)

### Wie suche ich nur in einem Teil des Bilds, und in welchem Koordinatensystem sind die Positionen? {#faq-search-region}

- **Antwort:** Setzen Sie `find-template/input/crop/` (`startX`, `startY`, `width`, `height`). Eine Breite oder Höhe von null reicht bis zum rechten bzw. unteren Rand; mit lauter Nullen wird also das ganze Bild durchsucht. Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nicht beschnitten, mit einer Meldung wie `crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640`. `input/result-coordinate` bestimmt das Koordinatensystem der Positionen: `IMAGE` (Standard, das ganze Bild, direkt für einen Robotergriff verwendbar) oder `CROP` (die durchsuchte Region, obere linke Ecke (0,0)).
- **Mehr:** [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html)

### Kann der Template Finder jedes Bild durchsuchen, das eine Kamera streamt? {#faq-image-stream}

- **Antwort:** Ja, als experimentelle Funktion. Ein Modul abonniert den Stream einer Kamera und durchsucht jedes Bild mit den Eingaben von `find-template` (alle außer `input/input-image-address`); es veröffentlicht ein Ergebnis pro Bild auf `<module-id>/control/subscribe/output/stream/result`:
  - Stellen Sie sicher, dass der Stream des Cam Driver läuft.
  - Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, auf `<module-id>/control/subscribe/input/address`.
  - Setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie auf `control/subscribe/execute`. Nur `enable` zu schreiben startet nichts.
  - Warten Sie, bis `control/subscribe/output/stream/active` `true` ist.
  - Was `control/subscribe/execute` anwendet, wird in `<module-id>.json` gespeichert; ein Modul, das gestreamt hat, streamt nach einem Neustart wieder. Für eine SPS schalten Sie `control/subscribe/input/keep-latest-output` ein und lesen `find-template/output/result`.
- **Mehr:** [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html), [Streams (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)

## Statuscodes und Fehler

### Woran erkenne ich, ob eine Operation erfolgreich war, 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 bedeutet Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht ausgeführt wurde, kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat. Der Grund steht auf `output/status-text`, der mit `ok:` oder `error:` beginnt. Ein fehlgeschlagener Schreibvorgang auf `execute` selbst antwortet nur mit einem Statuscode (über REST ein bloßes `400`); lesen Sie danach `output/status-text`. Derselbe Text wird in das Protokoll der Anwendung geschrieben: auf ctrlX OS in das ctrlX Logbook oder mit `journalctl`, auf einem PC in die Konsolenausgabe der Anwendung. `-1` (belegt) bedeutet, dass eine andere Operation desselben Moduls noch lief; es wurde nichts getan, versuchen Sie es also erneut, sobald sie abgeschlossen ist.
- **Mehr:** [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execute-a-method.html), [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html)

## Fehlerbehebung {#troubleshooting}

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

- [Statuscode `-1` (belegt)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-busy-while-streaming)
- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-2)
- [Statuscode `-3` (Bild konnte nicht gelesen werden)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Statuscode `-4` (Quelle nicht gefunden)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-status-minus-4)
- [Die Ausschnittsregion passt nicht in das Bild](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-crop-does-not-fit)
- [Statuscode `-6` (Schreiben fehlgeschlagen)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-status-minus-6)
- [Das Ergebnis ist leer, obwohl der Statuscode `1` ist](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-empty-result)
- [Die Vorlage wird nicht einmal in dem Bild gefunden, aus dem sie ausgeschnitten wurde](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-not-found-in-own-image)
- [Das Teil wird nicht gefunden, wenn es gedreht ist oder in einem anderen Abstand liegt](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-rotation-scale)
- [Eine weite Suche meldet schwache Treffer an falschen Stellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-spurious-matches)
- [`output/result` ist leer, obwohl die Suche eben noch funktioniert hat](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-result-empty)
- [Die Vorlagendatei liegt auf dem Gerät, fehlt aber in `system/templates`](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-template-not-listed)
- [Der Bild-Stream liefert keine Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-stream-no-results)
- [Meine Einstellungen oder Module sind nach einem Neustart weg](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-settings-lost)
- [Die Anwendung beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-app-stops-after-start)
- [Statuscode `-11` (Lizenz nicht verfügbar)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-licence-unavailable)

## Lizenzierung und Support

### Welche Lizenz benötige 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 befindet sich auf einem LumiScan Key (Windows 11 oder Ubuntu 24.04). Pro Gerät, auf dem die Software gleichzeitig läuft, wird ein LumiScan Key benötigt; 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.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html#licence), [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/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). Bevor Sie ein Problem für einen Support-Bericht reproduzieren, setzen Sie `logLevel` im Block `system` von `lumiscan-template-finder.json` auf `TRACE` und starten Sie die Anwendung neu.
- **Mehr:** [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html), [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

# Fehlerbehebung – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html

Diese Seite beschreibt Probleme und Fehlermeldungen von LumiScan Template Finder, nach Kategorien geordnet. Beginnen Sie mit den [allgemeinen Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#general-checks) und suchen Sie dann unten Ihr Symptom: Jedes Problem nennt die Symptome, die möglichen Ursachen, eine Diagnose und die Lösung. Probleme des Data Layer selbst sind in der [Fehlerbehebung des Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) beschrieben, Lizenzprobleme in der [Fehlerbehebung der Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/troubleshooting.html).

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

1. **Prüfen Sie den Statuscode.** Lesen Sie `output/status-code` der Operation, die fehlgeschlagen ist. Erwartet: `1`. Ein Wert größer als 0 bedeutet Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht ausgeführt wurde, und ein Wert kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat. Die Codes stehen in [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html).
2. **Lesen Sie den Statustext.** Lesen Sie `output/status-text` derselben Operation. Er beginnt mit `ok:` oder `error:` und nennt jede ungültige Eingabe und ihren Wert. Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST ein bloßes `400`); der Grund steht also nur auf `output/status-text`.
3. **Lesen Sie das Protokoll der Anwendung.** Es enthält denselben Text, mit einer eigenen Warnzeile für jede ungültige Eingabe: auf ctrlX OS im ctrlX Logbook oder mit `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung. Wie viel protokolliert wird, legt `logLevel` im Block `system` von `lumiscan-template-finder.json` fest (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` oder `OFF`); ohne den Schlüssel protokolliert die Anwendung auf `DEBUG`. Der Level wird einmal, beim Start, gelesen; starten Sie die Anwendung nach einer Änderung also neu. `TRACE` ist der Wert, den Sie setzen, bevor Sie ein Problem für einen Support-Bericht reproduzieren. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).
4. **Prüfen Sie die Bildquelle.** Die Kameraanwendung, normalerweise LumiScan Cam Driver, muss auf **demselben Gerät** laufen - demselben ctrlX CORE oder ctrlX IPC oder demselben PC - und ein Bild aufgenommen haben. Ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt. Erwartet: Der in `input/input-image-address` genannte Knoten stellt `data`, `width`, `height` und `pixel-type` bereit.
5. **Prüfen Sie die Reihenfolge der Aufrufe.** Ein Modul führt jeweils eine Operation aus, und jeder Durchlauf leert beim Start seine Ausgaben. Erwartet: Ihr Programm wartet, bis `execute` zurückkehrt, liest die Ausgaben und löst erst dann den nächsten Durchlauf aus.
6. **Prüfen Sie die Lizenz (ctrlX OS).** Erwartet: Die Anwendung läuft nach dem Start weiter. Ohne Lizenz beendet sie sich kurz nach dem Start; siehe [Problem: Die Anwendung beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-app-stops-after-start).

Das Konfigurationsverzeichnis enthält `lumiscan-template-finder.json`, die Moduldateien `<module-id>.json`, den Ordner `templates` und `settings-history/`:

| Plattform | Konfigurationsverzeichnis |
| --- | --- |
| ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder`, Teil der aktiven Solution |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-template-finder`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder` |

## Statuscodes und Fehlermeldungen {#ts-status-codes}

### Problem: Statuscode `-1` (belegt) {#faq-busy-while-streaming}

**Symptome**

`output/status-code` von `find-template` ist `-1`. Der Schreibvorgang auf `execute` antwortet mit `TooManyOperations` (ctrlX: `DL_TOO_MANY_OPERATIONS`). Es wurde nichts getan, und `output/result` behält seinen Wert. Bei einer streamenden Kamera passiert das häufig. Auch `system/remove-module` kann mit `-1` (belegt) antworten.

**Mögliche Ursachen**

- Eine andere Operation desselben Moduls lief noch. Ein zweiter Aufruf wird nicht in eine Warteschlange gestellt; er kehrt sofort zurück und tut nichts.
- Der Bild-Stream des Moduls durchsucht gerade ein Bild. Der Stream und `find-template` laufen auf einem Modul nie gleichzeitig.

**Diagnose**

1. Prüfen Sie in Ihrem Programm, ob es erneut auf `execute` desselben Moduls schreibt, bevor der vorherige Schreibvorgang zurückgekehrt ist. Erwartet: ein Aufruf pro Modul zur Zeit.
2. Lesen Sie `<module-id>/control/subscribe/output/stream/active`. `true` bedeutet, dass der Stream dieses Moduls läuft.

**Lösung**

- **Wenn eine andere Operation noch lief:** Warten Sie, bis das laufende `execute` zurückkehrt, und rufen Sie die Methode dann erneut auf. Die Sperre gilt pro Modul, andere Module werden also nicht aufgehalten.

- **Wenn der Stream des Moduls läuft:**

  a. Stoppen Sie den Stream, bevor Sie die Methode aufrufen: Setzen Sie `control/subscribe/input/enable` auf `false` und schreiben Sie auf `control/subscribe/execute`. Oder rufen Sie die Methode erneut auf.

  b. Um stattdessen die Ergebnisse des Streams zu verwenden, schalten Sie `control/subscribe/input/keep-latest-output` ein und lesen `find-template/output/result`.

- **Wenn `system/remove-module` mit belegt antwortet:** Stoppen Sie zuerst den Stream des Moduls. Das Entfernen eines Moduls stoppt seinen Stream.

Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execute-a-method.html) und [find-template bei laufendem Stream](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#while-streaming).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Modul-ID, der Antwort des Schreibvorgangs auf `execute` und dem Wert von `control/subscribe/output/stream/active`.

### Problem: Statuscode `-2` (ungültige Eingabe) {#faq-status-minus-2}

**Symptome**

`output/status-code` ist `-2`. `output/status-text` beginnt mit `error:` und nennt jede fehlerhafte Eingabe und ihren Wert, zum Beispiel `min-scale must be > 0, got 0`. Jede wird zusätzlich als Warnung protokolliert.

**Mögliche Ursachen**

- Eine erforderliche Eingabe ist leer: `input/input-image-address` oder `input/template-name`.
- Der Matching-Modus ist falsch geschrieben. `input/match-mode` akzeptiert `TM_SQDIFF`, `TM_SQDIFF_NORMED`, `TM_CCORR`, `TM_CCORR_NORMED`, `TM_CCOEFF` und `TM_CCOEFF_NORMED`.
- Ein Suchparameter liegt außerhalb des zulässigen Bereichs, zum Beispiel `input/scale/min-scale` oder `input/rotation/step-rot` nicht größer als 0 oder eine Drehung außerhalb von 0 bis 360.
- Die Bildadresse zeigt auf diese Anwendung selbst.
- Ein Ordner- oder Dateiname ist ein absoluter Pfad, etwa `/tmp/templates`, oder ein Pfad, der aus dem Konfigurationsverzeichnis hinausführt, etwa `../../etc`.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt jede fehlerhafte Eingabe und ihren Wert.
2. Lesen Sie das Protokoll der Anwendung. Jede fehlerhafte Eingabe wird als Warnung protokolliert.

**Lösung**

- **Wenn eine erforderliche Eingabe leer ist:** Setzen Sie sie. `input/template-name` nimmt einen Eintrag von `system/templates`.
- **Wenn der Matching-Modus falsch geschrieben ist:** Schreiben Sie einen der akzeptierten Namen auf `input/match-mode`.
- **Wenn ein Suchparameter außerhalb des Bereichs liegt:** Korrigieren Sie ihn, siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).
- **Wenn die Bildadresse auf diese Anwendung zeigt:** Setzen Sie `input/input-image-address` auf den Bildknoten der Kameraanwendung, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- **Wenn ein Pfad absolut ist oder das Konfigurationsverzeichnis verlässt:** Geben Sie ihn relativ zum Konfigurationsverzeichnis an. Ein Pfad, der innerhalb bleibt, ist auch dann in Ordnung, wenn er `..` enthält.

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html) und [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

**Wenn das Problem weiterhin besteht**

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

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

**Symptome**

`output/status-code` von `find-template` oder `system/create-template` ist `-3`.

**Mögliche Ursachen**

- Die Kameraanwendung läuft nicht, oder sie läuft auf einem anderen Gerät.
- Die Kameraanwendung hat noch kein Bild aufgenommen.
- Die Adresse in `input/input-image-address` ist falsch.
- Der Bildknoten an der Adresse fehlt, ist leer oder inkonsistent.
- Das Bild verwendet ein nicht unterstütztes Pixelformat. Unterstützt werden `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` und `BayerRG12`.

**Diagnose**

1. Prüfen Sie, ob die Kameraanwendung, normalerweise LumiScan Cam Driver, auf demselben Gerät läuft. Erwartet: Sie läuft auf demselben ctrlX CORE oder ctrlX IPC oder auf demselben PC.
2. Vergleichen Sie `input/input-image-address` mit der Adresse des Bildknotens der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Erwartet: identisch. `system/create-template` und `find-template` haben jeweils einen eigenen Adressknoten.
3. Lesen Sie `width`, `height` und `pixel-type` des Bildknotens. Erwartet: Werte größer als 0 und ein `pixel-type` aus der obigen Liste.

**Lösung**

- **Wenn die Kameraanwendung nicht läuft:** Starten Sie sie auf demselben Gerät und nehmen Sie ein Bild auf.
- **Wenn noch kein Bild aufgenommen wurde:** Nehmen Sie in der Kameraanwendung ein Bild auf.
- **Wenn die Adresse falsch ist:** Korrigieren Sie `input/input-image-address`.
- **Wenn das Pixelformat nicht unterstützt wird:** Verwenden Sie eines der unterstützten Pixelformate, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html).

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`, der Bildadresse und dem `pixel-type` des Bildknotens.

### Problem: Statuscode `-4` (Quelle nicht gefunden) {#faq-status-minus-4}

**Symptome**

`output/status-code` von `find-template` ist `-4`. `output/status-text` nennt ein Verzeichnis oder eine Datei.

**Mögliche Ursachen**

- Die Meldung nennt ein Verzeichnis: Der Vorlagenordner existiert nicht. Der Standardordner `templates` wird beim Start angelegt; entweder wurde er gelöscht, oder der Ordnername ist falsch.
- Die Meldung nennt eine Datei: Der Ordner existiert, enthält aber keine solche Datei.
- Die Datei ist vorhanden, wird aber nicht gefunden: Sie liegt in einem anderen Ordner als dem verwendeten. Alle Module teilen sich einen Vorlagenordner.

**Diagnose**

1. Lesen Sie `output/status-text`. Erwartet: Er nennt ein Verzeichnis oder eine Datei.
2. Vergleichen Sie `input/template-name` mit `system/templates`. Erwartet: Der Name ist aufgeführt, in derselben Schreibweise.
3. Lesen Sie `system/template-dir`. Erwartet: Es nennt den Ordner, der die Datei enthält.

**Lösung**

- **Wenn der Ordner nicht existiert:** Wechseln Sie mit `system/set-template-dir` zu einem vorhandenen Ordner, oder korrigieren Sie seinen Namen. Der Ordner muss bereits vorhanden sein; er wird nicht für Sie angelegt.
- **Wenn der Ordner keine solche Datei enthält:** Korrigieren Sie die Schreibweise von `input/template-name`, oder erstellen Sie die Vorlage mit `system/create-template`.
- **Wenn die Datei in einem anderen Ordner liegt:** Verschieben Sie die Datei in den Ordner, den `system/template-dir` nennt, oder wechseln Sie mit `system/set-template-dir`.

Führen Sie `find-template` dann erneut aus. Erwartet: `output/status-code` ist `1`. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`, `input/template-name`, `system/template-dir` und `system/templates`.

### Problem: Die Ausschnittsregion passt nicht in das Bild {#ts-crop-does-not-fit}

**Symptome**

`system/create-template` antwortet mit Status `-5` (ungültige Ausschnittsregion), und `output/status-text` nennt die tatsächliche Bildgröße. Bei `find-template` nennt `output/status-text` die Eingabe und die Grenze, die sie verletzt hat, zum Beispiel:

```
crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640
```

Im Bild-Stream schlägt das Bild fehl, und `control/subscribe/output/stream/last-failure` nennt eine Ausschnittsregion, die nicht in das Bild passt.

**Mögliche Ursachen**

- Die Region reicht über einen Rand des Bildes hinaus. Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nicht beschnitten.
- Bei `find-template` ist die Region kleiner als die Vorlage. Das wird mit Status `-5` abgelehnt.
- Bei `system/create-template` ist `input/crop/width` oder `input/crop/height` 0. Beide müssen größer als 0 sein.

**Diagnose**

1. Lesen Sie die Bildgröße aus der Meldung ab, oder `width` und `height` des Bildknotens.
2. Addieren Sie `input/crop/startX` und `input/crop/width` sowie `input/crop/startY` und `input/crop/height`. Erwartet: Die Summen sind nicht größer als die Bildbreite und die Bildhöhe.
3. Bei `find-template` vergleichen Sie die Region mit der Größe der Vorlage. Erwartet: Die Region ist mindestens so groß wie die Vorlage.

**Lösung**

- **Wenn die Region über einen Rand hinausreicht:** Korrigieren Sie `input/crop/startX`, `startY`, `width` oder `height`, sodass die Region in das Bild passt. Eine Breite oder Höhe von null reicht bis zum rechten bzw. unteren Rand.
- **Wenn die Region kleiner als die Vorlage ist:** Vergrößern Sie die Region.
- **Wenn Breite oder Höhe 0 ist (`create-template`):** Setzen Sie beide auf die Größe der Region, größer als 0.

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`. Siehe [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html) und [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).

**Wenn das Problem weiterhin besteht**

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

### Problem: Statuscode `-6` (Schreiben fehlgeschlagen) {#ts-status-minus-6}

**Symptome**

`output/status-code` von `system/save-module-inputs` oder `system/create-template` ist `-6`.

**Mögliche Ursachen**

- Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger.
- Das Konfigurationsverzeichnis ist nicht beschreibbar. Dasselbe Problem wird beim Start im Protokoll gemeldet.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt die Datei, die nicht geschrieben werden konnte.
2. Lesen Sie das Protokoll der Anwendung beim Start. Erwartet: keine Meldung, dass das Konfigurationsverzeichnis nicht beschreibbar ist.
3. Prüfen Sie das Konfigurationsverzeichnis (siehe [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#general-checks)). Erwartet: Es existiert, und die Anwendung kann hineinschreiben.

**Lösung**

- **Wenn das Konfigurationsverzeichnis nicht beschreibbar ist:** Machen Sie es für die Anwendung beschreibbar.
- **Wenn der Datenträger voll ist:** Geben Sie auf dem Gerät Speicherplatz frei.

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`.

**Wenn das Problem weiterhin besteht**

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

## Suchergebnisse {#ts-results}

### Problem: Das Ergebnis ist leer, obwohl der Statuscode `1` ist {#ts-empty-result}

**Symptome**

`output/status-code` von `find-template` ist `1`, aber `matches` in `output/result` ist leer, und `best_score` ist `0.0`.

**Mögliche Ursachen**

Eine leere Liste `matches` mit Statuscode `1` bedeutet, dass die Suche korrekt gelaufen ist und nichts gefunden hat. Das ist ein normales Ergebnis: Das Teil ist nicht da oder nicht ähnlich genug, um den Schwellwert zu erreichen. Wird ein vorhandenes Teil nicht gefunden:

- Die Vorlage wurde aus der falschen Region oder dem falschen Bild ausgeschnitten, siehe [Problem: Die Vorlage wird nicht einmal in dem Bild gefunden, aus dem sie ausgeschnitten wurde](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-not-found-in-own-image).
- Das Teil ist gedreht oder liegt in einem anderen Abstand als in der Vorlage, siehe [Problem: Das Teil wird nicht gefunden, wenn es gedreht ist oder in einem anderen Abstand liegt](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-rotation-scale).
- `input/crop` schließt das Teil aus.
- Die Vorlage berührt den Bildrand. Eine solche Vorlage kann nahe dem gegenüberliegenden Rand nicht gefunden werden, weil die Vorlage vollständig in das durchsuchte Bild passen muss.
- Die Vorlage enthält Hintergrund, der sich von Teil zu Teil ändert; er senkt jeden Score.

**Diagnose**

1. Lesen Sie `output/status-code`. Erwartet: `1`. Ist er negativ, ist der Durchlauf fehlgeschlagen: Lesen Sie `output/status-text` und sehen Sie sich die Einträge unter [Statuscodes und Fehlermeldungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-status-codes) an.
2. Durchsuchen Sie das Bild, aus dem die Vorlage ausgeschnitten wurde. Erwartet: ein Treffer in der Mitte der angegebenen Region, mit einer Konfidenz nahe 1.
3. Vergleichen Sie Ausrichtung und Größe des Teils im Bild mit der Vorlage.
4. Lesen Sie die vier Werte unter `input/crop/`. Erwartet: alle `0` (das ganze Bild) oder eine Region, die das Teil enthält.
5. Lesen Sie `match_thresh` in `output/result`: den angewendeten Schwellwert (Standard `0.9`).

**Lösung**

- **Wenn die Vorlage nicht in ihrem eigenen Bild gefunden wird:** Folgen Sie [Problem: Die Vorlage wird nicht einmal in dem Bild gefunden, aus dem sie ausgeschnitten wurde](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-not-found-in-own-image).
- **Wenn das Teil gedreht ist oder in einem anderen Abstand liegt:** Folgen Sie [Problem: Das Teil wird nicht gefunden, wenn es gedreht ist oder in einem anderen Abstand liegt](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-rotation-scale).
- **Wenn der Ausschnitt das Teil ausschließt:** Vergrößern Sie die Region, oder setzen Sie alle vier Werte unter `input/crop/` auf `0`.
- **Wenn die Vorlage den Bildrand berührt oder wechselnden Hintergrund enthält:** Erstellen Sie die Vorlage erneut aus einer Region, die vom Bildrand Abstand hält, das enthält, was das Teil kennzeichnet, und das ausschließt, was variiert. Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).
- **Wenn das Teil nicht im Bild war:** Das Ergebnis ist korrekt; es muss nichts geändert werden.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `input/template-name`, der Vorlagendatei und `output/result`.

### Problem: Die Vorlage wird nicht einmal in dem Bild gefunden, aus dem sie ausgeschnitten wurde {#faq-not-found-in-own-image}

**Symptome**

Eine Suche in genau dem Bild, aus dem die Vorlage ausgeschnitten wurde, meldet den Treffer nicht in der Mitte der angegebenen Region mit einer Konfidenz nahe 1.

**Mögliche Ursachen**

- Die beim Erstellen der Vorlage angegebene Region ist falsch.
- Die Bildadresse ist falsch: Die Vorlage wurde aus einem anderen Bild ausgeschnitten als dem durchsuchten. `system/create-template/input/input-image-address` und `<module>/find-template/input/input-image-address` sind getrennte Knoten.

Die Suchparameter sind nicht die Ursache, und keine Abstimmung behebt es.

**Diagnose**

1. Vergleichen Sie `system/create-template/input/input-image-address` mit `<module>/find-template/input/input-image-address`. Erwartet: derselbe Bildknoten.
2. Lesen Sie die vier Werte unter `system/create-template/input/crop/`. Erwartet: eine Region, die das Teil in diesem Bild enthält.
3. Lesen Sie `system/create-template/output/template-path`. Erwartet: die Datei, nach der Sie suchen, zum Beispiel `templates/screw.png`.

**Lösung**

- Korrigieren Sie `input/input-image-address` und die Ausschnittsregion, und erstellen Sie die Vorlage dann erneut. Bei einer Suche im selben Bild muss sie genau in der Mitte der angegebenen Region gefunden werden - (195, 250) für eine Region, die bei (100, 200) beginnt und 190 x 100 Pixel groß ist -, mit einer Konfidenz nahe 1.

Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html) und [Anleitung: Ein Teil in einem Kamerabild finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/how-tos/match-a-part-from-a-camera-image.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben von `system/create-template`, der Vorlagendatei und `output/result`.

### Problem: Das Teil wird nicht gefunden, wenn es gedreht ist oder in einem anderen Abstand liegt {#faq-rotation-scale}

**Symptome**

Die Vorlage wird in dem Bild gefunden, aus dem sie ausgeschnitten wurde, aber nicht in einem neuen Bild, in dem das Teil gedreht ist oder näher an der Kamera oder weiter von ihr entfernt liegt.

**Mögliche Ursachen**

- Die Standardwerte suchen die Vorlage nur in ihrer ursprünglichen Größe und Ausrichtung.

**Diagnose**

1. Lesen Sie `input/rotation/min-rot`, `max-rot` und `input/scale/min-scale`, `max-scale` des Moduls. Bei den Standardwerten (`0.0`, `0.0`, `1.0`, `1.0`) werden nur die ursprüngliche Ausrichtung und Größe gesucht.
2. Vergleichen Sie das Teil im neuen Bild mit der Vorlage. Erwartet: Sie wissen, ob es in der Ausrichtung, in der Größe oder in beidem variiert.

**Lösung**

Erweitern Sie nur, was tatsächlich variiert, einen Bereich nach dem anderen, und hören Sie auf, sobald das Teil zuverlässig gefunden wird:

- **Wenn sich das Teil dreht:** Setzen Sie `input/rotation/max-rot` (zum Beispiel `360`) mit einem groben `input/rotation/step-rot` (zum Beispiel `5`).
- **Wenn sich der Abstand des Teils ändert:** Setzen Sie `input/scale/min-scale`, `input/scale/max-scale` und `input/scale/step-scale` (zum Beispiel `0.9`, `1.1`, `0.05`).

Jede Kombination aus Skalierung und Drehung ist ein eigener Durchlauf über das Bild; 72 Drehungen und 5 Skalierungen sind also 360 Durchläufe. Liefert ein weiterer Bereich Treffer an falschen Stellen, siehe [Problem: Eine weite Suche meldet schwache Treffer an falschen Stellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#faq-spurious-matches). Siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben für Skalierung und Drehung und `output/result`.

### Problem: Eine weite Suche meldet schwache Treffer an falschen Stellen {#faq-spurious-matches}

**Symptome**

Mit einem Skalierungs- oder Drehungsbereich enthält `matches` den echten Treffer und daneben Treffer an Stellen, die nichts damit zu tun haben.

**Mögliche Ursachen**

- Die Konfidenz ist kein absolutes Maß. Die Score-Karte wird für jeden Skalierungs-/Drehungsschritt neu skaliert, sodass die beste Stelle jedes Schritts eine Konfidenz nahe 1 erreicht und `input/match-thresh` pro Schritt wirkt. Nur Wiederholungen an derselben Stelle werden entfernt; ein schwacher Treffer an einer anderen Stelle kann also weiterhin erscheinen.

**Diagnose**

1. Lesen Sie `matches[0]` und `best_score`. Erwartet: Der echte Treffer ist der Eintrag mit der höchsten Konfidenz, an Index 0.
2. Lesen Sie die Eingaben für Skalierung und Drehung. Eine Suche mit einer Skalierung und einer Drehung verhält sich wie erwartet; ein Bereich kann Scheintreffer melden.

**Lösung**

- Erhöhen Sie `input/match-thresh`, zum Beispiel auf `0.95`, oder verkleinern Sie den Skalierungs- und Drehungsbereich.

Siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).

**Wenn das Problem weiterhin besteht**

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

### Problem: `output/result` ist leer, obwohl die Suche eben noch funktioniert hat {#faq-result-empty}

**Symptome**

Ein Durchlauf hat Treffer erzeugt, und kurz danach ist `output/result` leer.

**Mögliche Ursachen**

- Der nächste Durchlauf hat begonnen. Jeder Durchlauf löscht seine eigenen Ausgaben, sobald er beginnt, noch vor allem, was fehlschlagen kann. Wer `execute` erneut auslöst und dann liest, erhält den neuen Durchlauf - möglicherweise fehlgeschlagen oder noch leer -, nicht den vorherigen.
- Ein mit `-1` (belegt) abgelehnter Aufruf löscht nichts; wurde der zweite Aufruf abgelehnt, ist das also nicht die Ursache.

**Diagnose**

1. Prüfen Sie die Reihenfolge der Aufrufe in Ihrem Programm. Erwartet: Es liest `output/result`, bevor es das nächste `execute` auslöst.
2. Lesen Sie `output/status-code` des letzten Durchlaufs. Ein negativer Wert bedeutet, dass dieser Durchlauf fehlgeschlagen ist und `output/result` leer hinterlassen hat.

**Lösung**

- **Wenn der nächste Durchlauf zu früh begonnen hat:** Warten Sie, bis `execute` zurückkehrt, lesen Sie die Ausgaben, und lösen Sie erst dann den nächsten Durchlauf aus.
- **Wenn der letzte Durchlauf fehlgeschlagen ist:** Folgen Sie dem Eintrag zu seinem Statuscode.

Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execute-a-method.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Abfolge der Aufrufe Ihres Programms.

## Vorlagen {#ts-templates}

### Problem: Die Vorlagendatei liegt auf dem Gerät, fehlt aber in `system/templates` {#faq-template-not-listed}

**Symptome**

Eine `.png`-Datei liegt im Vorlagenordner, aber `system/templates` führt sie nicht auf.

**Mögliche Ursachen**

- Die Datei ist auf anderem Weg in den Ordner gelangt - durch ein Hochladen über die ctrlX-Weboberfläche auf ctrlX OS oder durch Kopieren in den Ordner auf einem PC -, und die Liste wurde nicht aktualisiert. Die Liste wird beim Start aktualisiert, wenn `system/set-template-dir` erfolgreich ist und wenn `system/create-template` eine Vorlage speichert.
- Die Erweiterung ist nicht `.png` in Kleinbuchstaben. `SCREW.PNG` wird ignoriert.
- Die Datei liegt in einem anderen Ordner als dem verwendeten.

**Diagnose**

1. Lesen Sie `system/template-dir`. Erwartet: Es nennt den Ordner, der die Datei enthält.
2. Prüfen Sie den Dateinamen. Erwartet: Er endet auf `.png` in Kleinbuchstaben.

**Lösung**

- **Wenn die Erweiterung nicht `.png` in Kleinbuchstaben ist:** Benennen Sie die Datei mit `.png` in Kleinbuchstaben um.
- **Wenn die Liste nicht aktualisiert wurde:** Führen Sie `system/set-template-dir` erneut mit demselben Ordner aus. Erwartet: Sein Statuscode ist `1`, und `system/templates` führt die Vorlage auf.

Eine Vorlage, die bei laufender Anwendung hinzugefügt wird, kann sofort gesucht werden: Die Datei wird jedes Mal gelesen, nicht beim Start zwischengespeichert. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `system/template-dir`, `system/templates` und dem Dateinamen.

## Bild-Stream (experimentell) {#ts-stream}

### Problem: Der Bild-Stream liefert keine Ergebnisse {#ts-stream-no-results}

**Symptome**

`control/subscribe/output/stream/active` bleibt `false`, auf `control/subscribe/output/stream/result` treffen keine Ergebnisse ein, oder `control/subscribe/output/stream/statistics/failed-frames` wächst.

**Mögliche Ursachen**

- Nur die Eingaben wurden geschrieben. `control/subscribe/input/enable` allein zu schreiben startet nichts; `control/subscribe/execute` wendet die Eingaben an.
- `control/subscribe/execute` wurde abgelehnt (`Rejected`, ctrlX: `DL_INVALID_VALUE`): Stream-Modus ohne Adresse oder eine Warteschlangengröße außerhalb von `1` bis `64`.
- Die Einstellungsdatei `<module-id>.json` konnte nicht geschrieben werden, zum Beispiel weil sie kein gültiges JSON ist (`CreationFailed`, ctrlX: `DL_CREATION_FAILED`). Nichts wurde geändert.
- Der Stream des Cam Driver läuft nicht, es treffen also keine Bilder ein.
- Die Quelle kann nicht abonniert werden. Das Modul versucht es alle 5 Sekunden erneut, solange der Stream läuft, und protokolliert den ersten Fehlschlag.
- Bilder können nicht durchsucht werden, aus den Gründen, die `find-template` in seinem `status-text` nennt.

**Diagnose**

1. Lesen Sie `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active`. Erwartet: `true`.
2. Lesen Sie `setting/stream/enable` und `setting/stream/address` des Moduls. Erwartet: `true` und der Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Sie zeigen, was zuletzt angewendet wurde.
3. Prüfen Sie die Antwort des Schreibvorgangs auf `control/subscribe/execute`. Erwartet: `Ok` (ctrlX: `DL_OK`). Diese Methoden haben keinen `status-text`; der Grund für eine Ablehnung steht im Protokoll der Anwendung.
4. Lesen Sie `control/subscribe/output/stream/active`. Erwartet: `true`.
5. Lesen Sie `received-frames`, `processed-frames` und `failed-frames` unter `control/subscribe/output/stream/statistics/`. Der erste Zähler, der nicht wächst, zeigt, wo die Kette abbricht.
6. Wächst `failed-frames`, lesen Sie `control/subscribe/output/stream/last-failure`. Er nennt den Grund für das letzte fehlgeschlagene Bild, zum Beispiel:
   ```
   a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: template-name is empty
   ```

**Lösung**

- **Wenn nur die Eingaben geschrieben wurden:** Setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie auf `control/subscribe/execute`. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist.
- **Wenn der Aufruf abgelehnt wurde (`Rejected`, `DL_INVALID_VALUE`):** Schreiben Sie den Stream-Ordner der Kamera auf `control/subscribe/input/address`, setzen Sie `control/subscribe/input/queue-size` auf einen Wert von `1` bis `64` und schreiben Sie erneut auf `control/subscribe/execute`.
- **Wenn die Einstellungsdatei nicht geschrieben werden konnte (`CreationFailed`, `DL_CREATION_FAILED`):** Machen Sie `<module-id>.json` im Konfigurationsverzeichnis wieder zu gültigem JSON, ohne Kommentare, und schreiben Sie dann erneut auf `control/subscribe/execute`.
- **Wenn der Stream des Cam Driver nicht läuft:** Starten Sie ihn. Er bleibt nach einem Neustart nicht erhalten: Rufen Sie nach jedem Start sein `control/publish/execute` mit `enable` = `true` auf, und verbinden Sie zuerst die Kamera. Siehe [Ein Stream liefert nichts](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#stream-nothing).
- **Wenn die Quelle nicht abonniert werden kann:** Prüfen Sie, ob `control/subscribe/input/address` der Stream-Ordner der Kamera ist und der Cam Driver auf demselben Gerät läuft.
- **Wenn Bilder fehlschlagen:** Korrigieren Sie die Eingabe, die `last-failure` nennt, wie bei einem einzelnen Aufruf von `find-template`.

Siehe [Vorlagen in einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten unter `setting/stream/`, den Zählern unter `control/subscribe/output/stream/statistics/`, `control/subscribe/output/stream/last-failure` und der `<module-id>.json` des Moduls.

## Module, Einstellungen und Lizenzierung {#ts-modules}

### 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`, oder die Eingaben eines Moduls stehen wieder auf ihren Standardwerten.

**Mögliche Ursachen**

- Die Modulliste wurde nicht gespeichert. Einstellungen und neue Module sind sofort wirksam, aber erst dauerhaft, wenn sie gespeichert werden; die Modulliste und die Einstellungen jedes Moduls werden getrennt gespeichert.
- Die Einstellungen des Moduls wurden nicht gespeichert.
- Ein Speichern ist fehlgeschlagen: `system/save-module-inputs` oder `system/save-current-modules` hat nicht Status `1` gemeldet.
- `<module-id>.json` enthält Kommentare. Der Stream liest eine solche Datei, aber die Eingaben des Moduls werden dann beim Start nicht wiederhergestellt; das Protokoll meldet die Datei als unlesbar.
- Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen.

Ergebnisse werden nicht gespeichert; sie entstehen beim nächsten Durchlauf. Vorlagendateien sind bereits dauerhaft: Es sind Dateien im Konfigurationsverzeichnis, auf ctrlX OS Teil der aktiven Solution.

**Diagnose**

1. Lesen Sie `system/modules` nach dem Neustart. Erwartet: alle Ihre Module.
2. Prüfen Sie das Konfigurationsverzeichnis (siehe [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#general-checks)). Erwartet: `lumiscan-template-finder.json` nennt Ihre Module, und für jedes Modul, dessen Einstellungen Sie gespeichert haben, gibt es eine `<module-id>.json`.
3. Lesen Sie das Protokoll der Anwendung beim Start. Erwartet: keine als unlesbar gemeldete Moduldatei, keine übersprungene Einstellung.

**Lösung**

- **Wenn die Einstellungen oder die Modulliste nicht gespeichert wurden:**

  a. Setzen Sie `system/save-module-inputs/input/module-id` (zum Beispiel `module-1`) und schreiben Sie auf `system/save-module-inputs/execute`. Tun Sie das für jedes Modul.

  b. Schreiben Sie auf `system/save-current-modules/execute`.

  c. Prüfen Sie, dass beide Status `1` melden.

- **Wenn die Moduldatei Kommentare enthält:** Entfernen Sie sie aus `<module-id>.json`. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.

- **Wenn nach einem Update eine Einstellung übersprungen wurde:** Setzen Sie die Eingabe erneut und speichern Sie die Einstellungen des Moduls.

Die Bild-Stream-Einstellungen eines Moduls brauchen keinen zusätzlichen Schritt: `control/subscribe/execute` speichert sie selbst in `<module-id>.json`. Damit das Modul selbst wieder da ist, speichern Sie zusätzlich die Modulliste. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html) und [In der Einstellungsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#saving).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `lumiscan-template-finder.json` und den Moduldateien `<module-id>.json`.

### Problem: Die Anwendung beendet sich kurz nach dem Start {#faq-app-stops-after-start}

**Symptome**

Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start. Ihre Knoten unter `hdvisionsystems/lumiscan-template-finder` verschwinden aus dem Data Layer.

**Mögliche Ursachen**

- Die Lizenz fehlt. Der Grund wird in das Systemprotokoll geschrieben.
- Die Anwendung benötigt mehr Lizenzen, als installiert sind. Eine Lizenz deckt zehn Module ab, siehe [Problem: Statuscode `-11` (Lizenz nicht verfügbar)](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#ts-licence-unavailable).

**Diagnose**

1. Öffnen Sie das Systemprotokoll von ctrlX OS (ctrlX Logbook oder `journalctl`). Erwartet: Es nennt den Grund und die fehlende Lizenz.
2. Vergleichen Sie die Lizenz mit der ctrlX-Lizenz von LumiScan Template Finder, `SWL-W-XCx-TEMPLxFDxxHDVS-V1NN`. Erwartet: Sie ist auf dem Gerät installiert, auf dem die Anwendung läuft.

**Lösung**

- **Wenn die Lizenz fehlt:** Installieren Sie eine gültige Lizenz auf dem Gerät und starten Sie die Anwendung erneut. Erwartet: Sie läuft weiter, und ihre Knoten sind im Data Layer.

Siehe [Lizenz](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/requirements.html#licence) und [Meine ctrlX-App beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/troubleshooting.html#faq-ctrlx-app-stops).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Zeilen des Systemprotokolls, die die Lizenz nennen. Für Lizenzen wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

### Problem: Statuscode `-11` (Lizenz nicht verfügbar) {#ts-licence-unavailable}

**Symptome**

Ein Modul wird mit Statuscode `-11` abgelehnt.

**Mögliche Ursachen**

- Keine Lizenz auf dem Gerät deckt das Modul ab. Eine Lizenz deckt zehn Module ab; das elfte Modul belegt eine zweite Lizenz desselben Schlüssels.

**Diagnose**

1. Zählen Sie die Einträge von `system/modules`. Erwartet: nicht mehr als zehn Module pro Lizenz auf dem Gerät.
2. Lesen Sie `output/status-text` der Operation, die mit `-11` geantwortet hat.

**Lösung**

- **Wenn mehr Module existieren, als die Lizenzen abdecken:** Entfernen Sie die nicht benötigten Module mit `system/remove-module` und speichern Sie die Modulliste mit `system/save-current-modules`, oder beschaffen Sie eine weitere Lizenz.

Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `system/modules`. Für Lizenzen wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

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

Besteht ein Problem weiterhin, senden Sie diese Informationen an den Support:

- **Softwareversion:** die Version von LumiScan Template Finder, die Sie verwenden. Die Dateien in `settings-history/` im Konfigurationsverzeichnis halten sie als `software.version` fest.
- **Plattform:** ctrlX OS (ctrlX CORE oder ctrlX IPC) und die Version von ctrlX OS, oder ein PC mit Windows 11 oder Ubuntu 24.04. Nennen Sie auch die Bezugsquelle: HD Vision Systems oder ctrlX Store.
- **Data Layer:** der ctrlX Data Layer (ctrlX OS) oder LumiScan Keryx (PC). Auf einem PC auch die Data-Layer-Adresse, die die Anwendung verwendet.
- **Protokoll:** das Protokoll der Anwendung zum Zeitpunkt des Fehlers - auf ctrlX OS aus dem ctrlX Logbook oder mit `journalctl`, auf einem PC die Konsolenausgabe der Anwendung. Bevor Sie das Problem reproduzieren, setzen Sie `logLevel` im Block `system` von `lumiscan-template-finder.json` auf `TRACE` und starten Sie die Anwendung neu.
- **Zeitpunkt:** Datum und Uhrzeit des Fehlers.
- **Kommunikationsstatus:** `output/status-code` und `output/status-text` der fehlgeschlagenen Operation und die Antwort des Schreibvorgangs auf `execute` (zum Beispiel `TooManyOperations` oder `DL_TOO_MANY_OPERATIONS`).
- **Konfigurationsdateien:** `lumiscan-template-finder.json`, die `<module-id>.json` des betroffenen Moduls, die Vorlagendatei und, für den Bild-Stream, die Datei in `settings-history/`, die sein Einstellungs-Hash nennt. Wo sie liegen, steht unter [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/troubleshooting.html#general-checks).

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). Siehe auch [Bevor Sie den Support kontaktieren](https://docs.hdvisionsystems.com/de/faq.html#faq-before-contacting-support) in der LumiScan-FAQ.

# v1.1.0 - 2026.08.07 – LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/release-notes/v1-1-0-2026-08-07.html

Erstes funktionsfähiges Release von LumiScan Template Finder. Frühere Versionen registrierten zwar die Data-Layer-Knoten der Anwendung, lieferten aber ein festes Platzhalterergebnis; nichts aus dieser Liste war vorher nutzbar.

**Hinzugefügt:**

- **Template Matching.** `<module>/find-template/execute` durchsucht ein Kamerabild nach einer gespeicherten Vorlage und meldet jedes gefundene Vorkommen mit einer orientierten Bounding Box, einer Konfidenz sowie der Skalierung und Drehung, bei der der Treffer gefunden wurde. Die Suche deckt einen konfigurierbaren Bereich von Skalierungen und Drehungen ab. Siehe [Eine Vorlage finden](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html).
- **Erstellen einer Vorlage aus einem Live-Bild.** `system/create-template/execute` schneidet eine rechteckige Region aus einem Kamerabild aus und speichert sie als Vorlagen-PNG, sodass eine Vorlage direkt von der echten Kamera erzeugt werden kann, ohne Dateien zu übertragen. Die Operation gilt für die gesamte Anwendung: Die geschriebene Vorlage ist sofort für jedes Modul nutzbar. Siehe [Eine Vorlage erstellen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/creating-a-template.html).
- **Ergebnisse als FlatBuffer.** `<module>/find-template/output/result` enthält die Treffer zusammen mit dem Vorlagennamen, dem Matching-Modus und dem Schwellwert, die sie erzeugt haben, sodass ein gespeichertes Ergebnis später interpretiert werden kann, ohne zu wissen, wie die Suche konfiguriert war.
- **Mehrere Module.** Jede Konfiguration liegt unter `<module-id>/` mit eigenen Einstellungen und Ergebnissen; Module können im laufenden Betrieb über `system/create-module` und `system/remove-module` angelegt und entfernt werden. `system/save-current-modules` erhält den Satz über einen Neustart hinweg, `system/save-module-inputs` die Einstellungen eines Moduls. **Eine Lizenz gilt für zehn Module**; das elfte belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz es abdeckt. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/module-management.html).
- **Ein Vorlagenverzeichnis für die gesamte Anwendung.** `system/template-dir` benennt das Verzeichnis, aus dem jedes Modul Vorlagen liest und in das `create-template` sie schreibt; eine Vorlage muss also nur einmal erstellt werden. Ändern Sie es mit `system/set-template-dir`; die Wahl wird gespeichert und beim nächsten Start wiederhergestellt. Ein nicht vorhandenes Verzeichnis wird abgelehnt statt angelegt; ein Tippfehler wird also gemeldet, statt stillschweigend einen leeren Ordner zu erzeugen.
- **Eine Liste der verfügbaren Vorlagen.** `system/templates` meldet, was in diesem Verzeichnis liegt, ohne die Erweiterung `.png`, sodass ein Eintrag direkt in `<module>/find-template/input/template-name` übernommen werden kann, statt einen Dateinamen zu raten. Die Liste wird beim Start, bei einem Wechsel des Verzeichnisses und beim Speichern einer Vorlage durch `create-template` aktualisiert. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).
- **Nur einen Teil des Bilds durchsuchen.** `<module>/find-template/input/crop/` beschränkt die Suche auf ein Rechteck. Eine Breite oder Höhe von null reicht bis zum entsprechenden Rand; die Standardregion mit lauter Nullen durchsucht also das ganze Bild. Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nennt die Eingabe und die verletzte Grenze, statt passend beschnitten zu werden.
- **Wahl des Koordinatensystems, in dem die Positionen gemeldet werden.** `<module>/find-template/input/result-coordinate` ist `IMAGE` (Standard) für Positionen im ganzen Bild oder `CROP` für Positionen innerhalb der durchsuchten Region.
- **Der Suchbereich ist gruppiert.** Die Eingaben für Skalierung, Drehung und Vorverarbeitung liegen in eigenen Ordnern - `<module>/find-template/input/scale/`, `.../rotation/` und `.../preprocess/` -, sodass ein Data-Layer-Browser drei kleine Gruppen statt einer flachen Liste von vierzehn Werten zeigt.
- **Statusmeldung bei jeder Operation.** Jede Operation meldet `output/status-code` und `output/status-text`. Der Statuscode ist vorzeichenbehaftet, und das Vorzeichen allein sagt, ob die Operation erfolgreich war: negativ ist ein Fehler, null bedeutet, dass sie noch nicht ausgeführt wurde. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execution-status.html).
- **Speicherung der Vorlagen in der aktiven Solution.** Vorlagen sind PNG-Dateien im Konfigurationsverzeichnis der Anwendung; sie werden also beim Export der Solution mitgenommen und mit ihr auf einem anderen Gerät wiederhergestellt. Das Verzeichnis wird beim ersten Start angelegt, sodass es auf einer neuen Installation einen Ort zum Hochladen gibt. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).
- **Ein konfigurierbarer Log-Level.** `system/logLevel` in `lumiscan-template-finder.json` legt fest, wie viel die Anwendung protokolliert - `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` oder `OFF` -, im selben Block, den die anderen LumiScan-Anwendungen verwenden, sodass `TRACE` für einen Support-Bericht ein- und danach wieder ausgeschaltet werden kann. Der Wert wird beim Start gelesen; ein fehlender oder falsch geschriebener Wert lässt die Anwendung so gesprächig wie bisher. Siehe [Speicherung der Vorlagen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/template-storage.html).

**Hinweise:**

- Jede Methode löscht ihre eigenen Ausgabeknoten, sobald sie beginnt, noch vor allem, was fehlschlagen kann; ein fehlgeschlagener Durchlauf hinterlässt sie also leer, statt das Ergebnis eines früheren Durchlaufs zu behalten. Status `-1` (belegt) ist die Ausnahme: Dieser Aufruf wurde nie ausgeführt und lässt die Ausgaben der laufenden Operation unberührt. Die Ausgaben gehören daher zum Durchlauf, der gerade beginnt - lesen Sie sie, bevor Sie den nächsten auslösen. Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/execute-a-method.html).
- `system/template-dir` und `system/templates` sind schreibgeschützt. Das Verzeichnis wird nur über `system/set-template-dir` geändert, sodass die Liste nie von dem Verzeichnis abweichen kann, aus dem sie stammt.
- Nur Dateien, die auf `.png` in Kleinbuchstaben enden, werden auf `system/templates` aufgeführt; geben Sie `create-template` also einen Namen in Kleinbuchstaben. Eine auf anderem Weg in das Verzeichnis kopierte Datei ist sofort nutzbar, erscheint aber erst in der Liste, wenn diese aktualisiert wird.
- Doppelte Treffer werden entfernt, bevor das Ergebnis veröffentlicht wird. Die Suche über einen Bereich von Skalierungen oder Drehungen findet dasselbe Teil einmal pro Schritt; ohne diesen Schritt würde ein einzelnes Teil viele Male gemeldet.
- Die Treffer-Konfidenz wird für jeden Skalierungs-/Drehungsschritt neu skaliert; sie ist also kein absolutes Maß der Ähnlichkeit, und der Schwellwert gilt pro Schritt statt global. Das spielt nur eine Rolle, wenn ein Bereich durchsucht wird; erklärt wird es in [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/tuning-the-search.html).
- Verzeichnis- und Dateinamen werden immer relativ zum Konfigurationsverzeichnis interpretiert. Absolute Pfade und Pfade, die aus diesem Verzeichnis hinausführen, werden abgelehnt.

# LumiScan Template Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Eine Schraube, aus dem Kamerabild als Template „screw“ ausgeschnitten](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/intro/step-1.svg)<br><br>**Ein Template aus dem Bild schneiden.** Ein kleines Bild des Teils, direkt aus dem Livebild. | ![Zwei Schrauben gefunden, eine davon gedreht](https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/_images/intro/step-2.svg)<br><br>**Wiederfinden, gedreht oder skaliert.** Das Teil wird im eingestellten Dreh- und Skalierbereich gefunden. | Beispielergebnis<br><br><br><br><br><br><br>Mitte<br>195, 250 px<br><br><br>Konfidenz<br>0.98<br><br><br>Skalierung<br>1.05<br><br><br>Drehung<br>35°<br><br>**Das Ergebnis an die SPS geben.** Position, Konfidenz, Skalierung und Drehung jedes Treffers. |

LumiScan Template Finder findet ein bekanntes Teil im Kamerabild anhand eines kleinen Bildes davon, des Templates, und meldet Position, Konfidenz des Treffers sowie Skalierung und Drehung. Templates schneiden Sie direkt aus dem Livebild, ohne Dateiübertragung oder Bildbearbeitung. Typische Aufgaben sind Anwesenheitsprüfung, Positionsrückmeldung für den Robotergriff und Lageprüfung vor einem Montageschritt, auf ctrlX OS oder einem Windows- oder Ubuntu-PC.

LumiScan Template Finder 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. Dieses Handbuch behandelt beide Plattformen; wo sie sich unterscheiden, wird es gesagt.

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