--- title: "Eine Vorlage finden" product: "LumiScan Template Finder" component: "lumiscan-template-finder-de" version: "1.1.0" display_version: "1.1.0.7" latest_version: true language: "de" url: "https://docs.hdvisionsystems.com/de/lumiscan-template-finder-de/1.1.0/lumiscan-template-finder/finding-a-template.html" --- # Eine Vorlage finden – LumiScan Template Finder 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).