---
title: "Data-Layer-Referenz"
product: "LumiScan Object Finder"
component: "lumiscan-object-finder-de"
version: "1.1.0"
display_version: "1.1.0.7"
latest_version: true
language: "de"
url: "https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/datalayer-reference.html"
---

# Data-Layer-Referenz – LumiScan Object Finder

Jede Adresse unten ist relativ zu

```
hdvisionsystems/lumiscan-object-finder/
```

## Data Layer {#data-layer}

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

Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) nutzt LumiScan Object 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 Object 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 Object 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.

## Anwendungsweite Knoten

| Adresse | Typ | Zugriff | Beschreibung |
| --- | --- | --- | --- |
| `system/modules` | string[] | lesen | Die derzeit vorhandenen Module |
| `system/object-dir` | string | lesen | Verzeichnis, aus dem die Objektbilder gelesen werden, relativ zum Konfigurationsverzeichnis |
| `system/objects` | string[] | lesen | Objekte, nach denen gesucht werden kann, eines pro `.png` |
| `system/set-object-dir/execute` | Methode | schreiben | Zu einem anderen Objektverzeichnis wechseln |
| `system/set-object-dir/input/object-dir` | string | lesen/schreiben | Verzeichnis, zu dem gewechselt wird |
| `system/create-object/execute` | Methode | schreiben | Einen Ausschnitt eines Live-Bildes als Objekt speichern |
| `system/create-object/input/input-image-address` | string | lesen/schreiben | Bild, aus dem ausgeschnitten wird |
| `system/create-object/input/object-id` | string | lesen/schreiben | Name des Objekts; zugleich der Dateiname. Überschreibt ein bestehendes |
| `system/create-object/input/crop/startX` | int32 | lesen/schreiben | Linker Rand der auszuschneidenden Region |
| `system/create-object/input/crop/startY` | int32 | lesen/schreiben | Oberer Rand |
| `system/create-object/input/crop/width` | int32 | lesen/schreiben | Breite, muss > 0 sein |
| `system/create-object/input/crop/height` | int32 | lesen/schreiben | Höhe, muss > 0 sein |
| `system/create-object/output/object-path` | string | lesen | Vom letzten Durchlauf geschriebene Datei |
| `system/create-module/execute` | Methode | schreiben | Ein Modul hinzufügen |
| `system/create-module/input/module-id` | string | lesen/schreiben | Name für das neue Modul |
| `system/remove-module/execute` | Methode | schreiben | Ein Modul entfernen |
| `system/remove-module/input/module-id` | string | lesen/schreiben | Zu entfernendes Modul |
| `system/save-current-modules/execute` | Methode | schreiben | Die Modulliste dauerhaft speichern |
| `system/save-module-inputs/execute` | Methode | schreiben | Die Einstellungen eines Moduls dauerhaft speichern |
| `system/save-module-inputs/input/module-id` | string | lesen/schreiben | Zu speicherndes Modul |
| `system/meta/subscription-schema` | string | lesen | Was der Knoten enthalten muss, den ein Modul abonniert, als JSON Schema (draft-04) seiner JSON-Form: hier ein `stream_image`, der Knoten `frame` des Stream-Ordners, mit `lineage` und `image`. Für jedes Modul gleich. Experimentell |

Jede Methode bedient außerdem `output/status-code` und `output/status-text`. Auf ctrlX OS deckt eine Lizenz zehn Module ab, siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/module-management.html).

## Knoten pro Modul

Alle Adressen unten liegen unter `<module-id>/find-object/`.

| Adresse | Typ | Zugriff | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| `execute` | Methode | schreiben | - | Eine Erkennung ausführen |
| `input/input-image-address` | string | lesen/schreiben | (leer) | Adresse des zu durchsuchenden Bildknotens |
| `input/object-id` | string | lesen/schreiben | (leer) | Gesuchtes Objekt. **Erforderlich** - ein leerer Wert wird abgelehnt |
| `input/confidence-threshold` | float64 | lesen/schreiben | 0.6 | Kleinster akzeptierter Score, 0 bis 1 |
| `input/nms-min-dist` | float64 | lesen/schreiben | 0.0 | Mindestabstand in Pixeln zwischen zwei Treffern |
| `input/pyramid` | uint8[] | lesen/schreiben | [1,2] | Ebenen der Bildpyramide, auf denen gesucht wird. Keine Geschwindigkeitseinstellung |
| `input/result-coordinate` | string | lesen/schreiben | IMAGE | `IMAGE` oder `CROP` |
| `input/crop/startX` | uint16 | lesen/schreiben | 0 | Linker Rand der zu durchsuchenden Region |
| `input/crop/startY` | uint16 | lesen/schreiben | 0 | Oberer Rand |
| `input/crop/width` | uint16 | lesen/schreiben | 0 | Breite; 0 reicht bis zum rechten Rand |
| `input/crop/height` | uint16 | lesen/schreiben | 0 | Höhe; 0 reicht bis zum unteren Rand |
| `input/preprocess/bin-size` | int32 | lesen/schreiben | 1 | Suche mit 1/N der Auflösung: schneller, weniger präzise. 1 deaktiviert es |
| `input/preprocess/blur-sigma-x` | float64 | lesen/schreiben | 0.0 | Gauß-Glättung in X; 0 oder weniger deaktiviert sie |
| `input/preprocess/blur-sigma-y` | float64 | lesen/schreiben | 0.0 | Gauß-Glättung in Y; 0 bedeutet wie X |
| `input/preprocess/blur-kernel-size-x` | uint32 | lesen/schreiben | 0 | Glättungskernel in X; 0 berechnet ihn, sonst ungerade |
| `input/preprocess/blur-kernel-size-y` | uint32 | lesen/schreiben | 0 | Glättungskernel in Y; 0 berechnet ihn, sonst ungerade |
| `output/result` | flatbuffers | lesen | leer | Treffer des letzten Durchlaufs |
| `output/status-code` | int16 | lesen | 0 | Ausgang als Zahl |
| `output/status-text` | string | lesen | (leer) | Ausgang in Worten |

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

Alle Adressen unten liegen unter `<module-id>/`, neben `find-object/`. Der Stream durchsucht jedes Bild mit den Eingaben von `find-object`, alle außer `input/input-image-address`. Siehe [Objekte auf einem Bild-Stream finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html).

| Adresse | Typ | Zugriff | Standard | Beschreibung |
| --- | --- | --- | --- | --- |
| `control/subscribe/input/enable` | bool | lesen/schreiben | wie angewendet | Stream-Modus: `true` lässt den Stream laufen, `false` stoppt ihn |
| `control/subscribe/input/address` | string | lesen/schreiben | 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 | lesen/schreiben | 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 | lesen/schreiben | wie angewendet | Bilder, die warten dürfen, während eines durchsucht wird, 1-64 |
| `control/subscribe/input/keep-latest-output` | bool | lesen/schreiben | wie angewendet | `true` schreibt jedes Stream-Ergebnis zusätzlich nach `find-object/output/result` |
| `control/subscribe/execute` | Methode | schreiben | - | Prüft die Eingaben von `control/subscribe` gemeinsam, speichert sie als `stream` in `<module-id>.json` und wendet sie dann an. Eine Eingabe allein zu schreiben ändert nichts |
| `control/unsubscribe/execute` | Methode | schreiben | - | Entfernt die Quelle, die `control/unsubscribe/input/address` nennt, was den Stream-Modus beendet; das Tag bleibt. Wie ein Subscribe in `<module-id>.json` gespeichert |
| `control/unsubscribe/input/address` | string | lesen/schreiben | (leer) | Die zu entfernende Quelle, wie `setting/stream/address` sie zeigt |
| `setting/stream/{enable, address, tag, queue-size, keep-latest-output}` | wie die Eingaben | lesen | `stream` in `<module-id>.json` | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat |
| `setting/settings-hash` | string | lesen | - | Hash dessen, womit die Ergebnisse erzeugt werden, 16 Hexadezimalziffern |
| `control/subscribe/output/stream/active` | bool | lesen | false | `true`, solange der Stream läuft |
| `control/subscribe/output/stream/result` | flatbuffers | lesen | leer | Ein `stream_object_matches` pro durchsuchtem Bild. Abonnieren Sie ihn, um jedes zu erhalten |
| `control/subscribe/output/stream/last-failure` | string | lesen | (leer) | 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 | lesen | 0 | Millisekunden seit dem Start des Streams |
| `control/subscribe/output/stream/statistics/received-frames` | uint64 | lesen | 0 | Bilder, die das Abonnement geliefert hat |
| `control/subscribe/output/stream/statistics/processed-frames` | uint64 | lesen | 0 | Durchsuchte Bilder, jedes mit einem Ergebnis |
| `control/subscribe/output/stream/statistics/skipped-frames` | uint64 | lesen | 0 | Bilder, die aus der Warteschlange verdrängt wurden oder warteten, als die Quelle ersetzt oder entfernt wurde |
| `control/subscribe/output/stream/statistics/failed-frames` | uint64 | lesen | 0 | Bilder, die nicht durchsucht werden konnten |
| `control/subscribe/output/stream/statistics/lost-frames` | uint64 | lesen | 0 | Bilder, die verloren gingen, bevor sie ankamen |
| `control/subscribe/output/stream/statistics/processing-us` | uint64 | lesen | 0 | 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).

## Der Ergebnis-Flatbuffer

`output/result` enthält `hdv.object_find.Result`:

| Feld | Typ | Bedeutung |
| --- | --- | --- |
| `matches` | Match[] | Alle Treffer, nach Score absteigend sortiert |
| `matches[].x`, `.y` | int | Linke obere Ecke der gefundenen Vorlage, in Pixeln |
| `matches[].width`, `.height` | int | Größe der Vorlage, die übereingestimmt hat |
| `matches[].score` | float | Ähnlichkeit von 0.0 bis 1.0 |
| `matches[].object_id` | string | Das gefundene Objekt; bei jedem Treffer eines Durchlaufs dasselbe |
| `best_index` | ulong | Index des besten Treffers; 0, wenn es keinen gibt |
| `best_score` | float | Score des besten Treffers; 0.0, wenn es keinen gibt |
| `best_object_id` | string | Objekt des besten Treffers; leer, wenn es keinen gibt |
| `image_width`, `image_height` | uint | Der Bildausschnitt, in dem die Koordinaten liegen |
| `confidence_threshold` | float | Der angewendete Schwellwert |
| `timestamp` | ulong | Mikrosekunden seit Epoche, beim Abschluss des Durchlaufs |

`control/subscribe/output/stream/result` enthält `hdv.stream.StreamObjectMatches` (`stream_object_matches`, registriert als `types/hdvisionsystems/lumiscan-object-finder/stream_object_matches`): `lineage`, woher das Bild kam, und `result`, das `hdv.object_find.Result` von oben.

## Konfigurationsdatei

Die Anwendungs-Einstellungsdatei `lumiscan-object-finder.json` liegt im Konfigurationsverzeichnis:

| Plattform | Datei |
| --- | --- |
| ctrlX OS | `<active solution>/lumiscan-object-finder/lumiscan-object-finder.json` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-object-finder\lumiscan-object-finder.json`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-obj-find\etc\lumiscan-object-finder\lumiscan-object-finder.json` |

```json
{
    "system": { "logLevel": "INFO" },
    "object-dir": "templates",
    "modules": [ { "id": "module-1", "advanced": false } ]
}
```

`logLevel` akzeptiert `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` und `OFF` und wird beim Start gelesen. Die gespeicherten Einstellungen jedes Moduls liegen daneben in `<module-id>.json`, ebenso Modus, Quelle, Warteschlangengröße und keep-latest-output seines Bild-Streams, unter `stream`.

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

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

```shell
lumiscan-obj-find --generate-settings C:\work\object-finder-settings
```

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

Der Object 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-obj-find\etc\lumiscan-object-finder`. Bearbeiten Sie das Beispiel, kopieren Sie es dorthin und starten Sie den Object Finder. Siehe auch [Speicherorte der Dateien (Windows)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files).