--- title: "Data-Layer-Referenz" 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/datalayer-reference.html" --- # Data-Layer-Referenz – LumiScan Template Finder 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 └── / 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 | ## \/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 | ## \ Bild-Stream (experimentell) {#module_stream} Die folgenden Adressen sind relativ zu `/`, 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 `.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 `.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 `.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).