# LumiScan Object Finder 1.1.0.7 – complete documentation

> All pages of the LumiScan Object 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-object-finder-de/1.1.0/

# Beschreibung – LumiScan Object Finder

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

LumiScan Object Finder findet bekannte Objekte in einem Kamerabild anhand ihrer **Form**. Sie beschreiben ein Objekt mit einem oder mehreren kleinen Bildern von ihm - seinen **Vorlagen** -, und die Anwendung meldet, wo dieses Objekt in einem größeren Bild erscheint, wie gut es übereinstimmt und mit welchem Ihrer Bilder es übereinstimmt.

Typische Einsatzfälle sind Anwesenheits- und Zählprüfungen, Positionsrückmeldung für einen Robotergriff, das Sortieren gemischter Teile auf einem Band 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-object-finder-de/1.1.0/lumiscan-object-finder/datalayer-reference.html).

Was für jede LumiScan-App gleich ist - wie Adressen aufgebaut sind, der Handshake, die Aufrufmuster 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 Object Finder ist; seine eigenen Knoten sind in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/datalayer-reference.html) aufgeführt.

## Wie ein Objekt erkannt wird

Das Matching erfolgt auf der **Kontur** des Objekts - der Richtung, in der sich die Helligkeit über seine Kanten hinweg ändert - und nicht auf den Helligkeitswerten selbst. Das hat zwei praktische Folgen.

Es ist **tolerant gegenüber Beleuchtung und Oberflächenbeschaffenheit**. Ein Teil, das in einer Zelle glänzend und in einer anderen matt ist oder aus einem anderen Winkel beleuchtet wird, zeigt immer noch dieselbe Kontur. Intensitätsbasiertes Matching hat hier Schwierigkeiten.

Es ist **von sich aus nicht tolerant gegenüber Rotation und Größe**. Die Anwendung dreht oder skaliert Ihre Vorlage nicht auf der Suche nach einer Übereinstimmung. Stattdessen wird ein Objekt durch **mehrere Vorlagen** beschrieben - eine pro Orientierung oder Arbeitsabstand, die Sie erkennen möchten. Vier Vorlagen erkennen vier Orientierungen.

> [!NOTE]
> Das ist der wesentliche Unterschied zu **LumiScan Template Finder**, der Helligkeiten korreliert und einen Bereich von Skalierungen und Rotationen durchsucht und ein orientiertes Rechteck meldet. Object Finder ist schneller und deutlich robuster gegenüber Beleuchtung und meldet ein achsenparalleles Rechteck sowie den Namen des gefundenen Objekts. Wählen Sie Object Finder, wenn Beleuchtung oder Oberfläche variieren und die Orientierungen bekannt sind; wählen Sie Template Finder, wenn der Winkel kontinuierlich und unbekannt ist.

## Was die Anwendung tut

Die Anwendung bietet zwei Operationen.

**Eine Vorlage anlegen** schneidet eine rechteckige Region aus einem Live-Kamerabild aus und speichert sie als weitere Ansicht eines Objekts. So lernen Sie ein Objekt mit der echten Kamera, in der echten Beleuchtung, im echten Arbeitsabstand ein - ohne Dateiübertragung und ohne Bildbearbeitungsprogramm. Siehe [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html).

**Ein Objekt finden** durchsucht ein Live-Kamerabild und meldet jedes gefundene Vorkommen. Siehe [Ein Objekt finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html).

Beide 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 [Objekte auf einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html).

## Woher die Bilder kommen

Die Anwendung kommuniziert nicht selbst mit einer Kamera. Sie liest einen Bildknoten, den eine andere Anwendung auf dem Data Layer veröffentlicht und der als Adresse angegeben wird, zum Beispiel:

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

Der Knoten muss `data`, `width`, `height` und `pixel-type` veröffentlichen - genau das, was LumiScan Cam Driver bereitstellt.

## Objekte und Module

Ein **Objekt** ist etwas, das Sie finden möchten - eine Schraube, ein Halter -, beschrieben durch seine Vorlagen. Objekte gehören zur gesamten Anwendung, sodass ein einmal eingelerntes Objekt von jedem Modul gefunden werden kann.

Ein **Modul** ist eine konfigurierte Instanz der Suche: mit eigener Kameraadresse, eigenen Einstellungen und eigenen Ergebnissen unter einer eigenen Data-Layer-Adresse. Eine Installation kann mehrere Module betreiben, um mehrere Kameras gleichzeitig zu überwachen. 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).

# Voraussetzungen – LumiScan Object Finder

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

## Lizenz {#licence}

Wie LumiScan Object 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-OBJECTxFDxHDVS-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 Object 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 ist für den Data Layer nichts zu installieren.

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

## Eine Bildquelle auf demselben Gerät

Die Anwendung liest ihre Bilder vom Data-Layer-Bildknoten einer anderen Anwendung. Diese Anwendung muss auf **demselben Gerät** laufen - demselben ctrlX CORE oder 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 funktioniert, solange ihr Bildknoten diese vier Unterknoten bereitstellt:

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `data` | Array von 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, die aus einem Format ausgeschnitten wurden, auch in Bildern eines anderen Formats gefunden werden.

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

## Speicher

Vorlagen werden als PNG-Dateien im Konfigurationsverzeichnis der Anwendung abgelegt. Auf ctrlX OS ist dieses Verzeichnis Teil der aktiven Solution. Planen Sie die Größe der Vorlagen ein, die Sie aufbewahren möchten - eine Vorlage ist ein kleiner Ausschnitt, typischerweise einige zehn Kilobyte.

Das Verzeichnis wird beim ersten Start angelegt. Siehe [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-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, nie gelöscht. Siehe [Objekte auf einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 breit der durchsuchte Skalierungs- und Rotationsbereich ist - die Arbeit ist ein Durchlauf pro Kombination aus Skalierung und Rotation.

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

# Eine Methode ausführen – LumiScan Object Finder

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

Jede Operation dieser Anwendung - Matching, Anlegen von Vorlagen und Modulverwaltung - wird auf dieselbe Weise gestartet und meldet ihren Ausgang 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 unter `output/` mehr - 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 braucht.

## Den Ausgang prüfen

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

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

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

`output/status-text` enthält denselben Ausgang als Satz und benennt 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-object-finder-de/1.1.0/lumiscan-object-finder/execution-status.html).

> [!NOTE]
> Der Grund kommt auf `output/status-text` an, nicht in der Antwort auf den `execute`-Schreibvorgang selbst. Ein fehlgeschlagener Schreibvorgang antwortet nur mit einem Statuscode - über REST ein bloßes `400`. Der Data Layer verwirft jedes Detail, das ein Provider an einen fehlgeschlagenen Aufruf anhängt. Deshalb ist das anschließende Lesen von `output/status-text` 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 Anwendungsprotokoll geschrieben, sodass ein Fehler auch ganz ohne Zugriff auf 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. Wird eine zweite gestartet, während die erste noch läuft, wird sie nicht in eine Warteschlange gestellt - sie kehrt sofort mit Statuscode `-1` (busy) 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 von der ersten nicht aufgehalten. `system/create-object` hat eine eigene Sperre, sodass das Anlegen einer Vorlage das Matching nicht blockiert und zwei Anlagevorgänge nicht kollidieren können.

## Die Ausgaben gehören zum startenden Durchlauf

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

Das macht 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 das ist ihr Zweck.

> [!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. Erneut `execute` aufzurufen und dann das vorherige Ergebnis zu lesen, liefert nichts.
>
> Der einzige Fall, der **nichts** leert, ist ein als `-1` (busy) abgelehnter Aufruf: Er ist nie gelaufen und lässt die Ausgaben der laufenden Operation unberührt. Ein zweites `execute`, das unmittelbar nach dem ersten abgesetzt wird, hat also zwei mögliche Ausgänge, und sie unterscheiden sich:
>
> - der erste Durchlauf **läuft noch** - der zweite wird mit `-1` abgelehnt, und die Ausgaben enthalten noch den Durchlauf davor;
> - der erste Durchlauf ist **gerade fertig** - der zweite wird angenommen und leert die Ausgaben, die der erste 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 Object Finder

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

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

## Statuscodes

| Code | Bedeutung | Wann er auftritt |
| --- | --- | --- |
| `0` | Idle | Die Operation ist seit dem Start der Anwendung nicht gelaufen |
| `1` | OK | Die Operation wurde abgeschlossen. Eine Suche kann trotzdem nichts gefunden haben - das ist ein normales Ergebnis, kein Fehler |
| `-1` | Busy | Eine andere Operation desselben Moduls lief noch. Es wurde nichts getan; versuchen Sie es erneut, wenn sie abgeschlossen ist |
| `-2` | Ungültige Eingabe | Ein Eingabewert kann nicht verwendet werden - ein erforderlicher Knoten leer gelassen, ein unbekannter Match-Modus, eine Bildadresse, die auf diese Anwendung selbst zeigt, oder ein Verzeichnispfad, der absolut ist oder aus dem Konfigurationsverzeichnis hinausführt |
| `-3` | Bild lesen fehlgeschlagen | Der Bildknoten an der angegebenen Adresse fehlt, ist leer, inkonsistent oder verwendet ein nicht unterstütztes Pixelformat. Prüfen Sie, ob die Kameraanwendung läuft und ein Bild aufgenommen hat |
| `-4` | Quelle nicht gefunden | Das Objektverzeichnis oder das Bild des Objekts fehlt oder ist nicht lesbar. Prüfen Sie den Namen anhand von `system/objects` |
| `-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` für die aktuelle Liste |
| `-10` | Modul existiert bereits | Ein Modul mit diesem Namen ist bereits vorhanden |
| `-11` | Lizenz nicht verfügbar | Keine Lizenz deckt das Modul ab. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/module-management.html) |

Diese Codes sind der eigene Ausführungsstatus der Finder, nicht die Modul-Statuscodes von Cam Driver oder 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 ihre Bedeutung nie, sodass darauf aufbauende Logik nach einem Update weiter funktioniert.
>
> Auch deshalb ist die Prüfung des **Vorzeichens** der robustere Test: `status-code < 0` bleibt korrekt, selbst wenn ein Release einen Fehler einführt, den Ihr Programm noch nie gesehen hat.

## Welche Operation welche Codes meldet

| Operation | Mögliche Codes |
| --- | --- |
| Ein Objekt finden | `1`, `-1`, `-2`, `-3`, `-4`, `-7`, `-8` |
| Ein Objekt anlegen | `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 gleichzeitig mit dem Statuscode geschrieben, sodass beide immer übereinstimmen.

Jede Operation hat ein eigenes Knotenpaar, und die Werte bleiben erhalten, bis diese Operation erneut läuft. Ein fehlgeschlagenes Anlegen einer Vorlage stört daher nicht das Ergebnis der letzten Suche.

# Ein Objekt anlegen – LumiScan Object Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html

`system/create-object` schneidet ein Rechteck aus einem Live-Kamerabild aus und speichert es als Objekt. So lernen Sie ein Objekt mit der echten Kamera, in der echten Beleuchtung, im echten Arbeitsabstand ein.

Es ist eine **anwendungsweite** Operation, keine modulbezogene: Sie schreibt in das eine Objektverzeichnis, das alle Module teilen, sodass ein einmal eingelerntes Objekt von jedem Modul gefunden werden kann.

## Eingaben

| Knoten | Bedeutung |
| --- | --- |
| `input/input-image-address` | Adresse des Bildknotens, aus dem ausgeschnitten wird. |
| `input/object-id` | Der Name des Objekts. Wird zu `<object-id>.png` und erscheint auf `system/objects`. Ein bestehendes Objekt dieses Namens wird **überschrieben**. |
| `input/crop/startX`, `startY` | Linke obere Ecke der auszuschneidenden Region. |
| `input/crop/width`, `height` | Größe der Region. Beide müssen größer als 0 sein. |

## Ein Objekt einlernen

1. Legen Sie das Teil in der Orientierung vor die Kamera, in der es tatsächlich ankommt.
2. Setzen Sie `object-id` auf den Namen des Objekts.
3. Setzen Sie den Ausschnitt um das Teil und schreiben Sie auf `execute`.

```
system/create-object/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
system/create-object/input/object-id           = screw-m6
system/create-object/input/crop/startX         = 820
system/create-object/input/crop/startY         = 400
system/create-object/input/crop/width          = 160
system/create-object/input/crop/height         = 120
write system/create-object/execute
```

Das Bild wird nach `<object-dir>/screw-m6.png` geschrieben, und `system/objects` übernimmt es sofort.

## Mehrere Orientierungen

Der Detektor dreht das Bild nicht, also ist ein Objekt ein Erscheinungsbild. Ein Teil, das in mehr als einer Orientierung ankommt, braucht **ein Objekt pro Orientierung** - `screw-m6-front`, `screw-m6-tilted` - und einen `find-object`-Durchlauf für jedes.

> [!TIP]
> **Beginnen Sie mit den Orientierungen, in denen das Teil wirklich ankommt.** Jede zusätzliche Ansicht kostet etwas Matching-Zeit und bringt Toleranz gegenüber genau dieser Orientierung - Ansichten, die Sie nie sehen werden, bringen nichts.

## Wie eng der Ausschnitt sein sollte

Lassen Sie **einige Pixel Hintergrund** um das Teil - aber nur wenige. Beide Richtungen kosten etwas, und die zu enge Seite ist diejenige, die unbemerkt fehlschlägt.

Der Detektor stützt sich auf Gradienten, und eine Kante existiert nur dort, wo auf der anderen Seite etwas anderes ist. Schneiden Sie genau entlang der Silhouette des Teils, ist auf der anderen Seite nichts, und die Kontur erzeugt **überhaupt keine Merkmale**. Der Detektor glättet mit 7x7 und wendet dann einen 3x3-Sobel an, beide mit nach außen replizierten Randpixeln. Daher verwirft er den äußersten Ring des Bildes und berechnet etwa 4 Pixel von jedem Rand nach innen abgeschwächte Gradienten.

> [!WARNING]
> Ein Ausschnitt, der an der Silhouette endet, verbirgt die Kontur des Teils vor dem Detektor. Entweder wird das Objekt **rundweg abgelehnt** - gemeldet als fehlgeschlagener Durchlauf, der es benennt, denn eine Vorlage muss eine Mindestzahl starker Gradientenpunkte liefern - oder es wird angenommen, aber nur auf die inneren Details des Teils gestützt. Der Detektor verkleinert die Vorlage auf die Region, in der er Merkmale gefunden hat, und matcht dann auf weniger, als das Bild zeigt; ein Teil, das sich vor allem durch seine Kontur auszeichnet, matcht dann schlecht.

Etwa **5 Pixel Rand genügen**, und mehr bringt nichts. Hintergrund innerhalb der Vorlage ist Hintergrund, den der Detektor dann zu sehen erwartet. Ein zu weiter Ausschnitt, der eine Werkbankkante oder ein benachbartes Teil einschließt, macht das Matching also weniger zuverlässig. Streben Sie ein dünnes, gleichmäßiges Band der Oberfläche an, auf der das Teil normalerweise liegt.

Bei Erfolg meldet `output/object-path` die geschriebene Datei, relativ zum Konfigurationsverzeichnis, und `system/objects` wird aktualisiert. Jedes Modul trainiert vor seiner nächsten Erkennung neu, sodass eine neue Ansicht sofort nutzbar ist.

## Fehler

Der gesamte Ausschnitt muss innerhalb des Bildes liegen. Eine Region, die darüber hinausgeht, wird abgelehnt; die Meldung nennt den Rand und die Bildgröße:

```
error: Crop region does not fit inside the 1920x1080 image: crop/startY + crop/height
(1000 + 200 = 1200) exceeds the image height 1080
```

`object-id` wird relativ zum Konfigurationsverzeichnis interpretiert. Ein absoluter Pfad oder einer, der mit `..` hinausführt, wird mit Status `-2` abgelehnt.

`output/object-path` wird geleert, wenn ein Durchlauf beginnt, sodass ein fehlgeschlagener Durchlauf nie einen Pfad auf eine Vorlage hinterlässt, die er nicht geschrieben hat. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execution-status.html).

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

- [Die Ausschnittsregion passt nicht in das Bild](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-crop-does-not-fit)
- [Der Durchlauf schlägt fehl und benennt das Objekt](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-object-refused-bin-size)
- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-status-minus-2)

# Ein Objekt finden – LumiScan Object Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html

`<module>/find-object` durchsucht ein Bild einmal nach einem bekannten Objekt.

## Eingaben

| Knoten | Standard | Bedeutung |
| --- | --- | --- |
| `input/input-image-address` | (leer) | Adresse des zu durchsuchenden Bildknotens. |
| `input/object-id` | (leer) | Welches Objekt gesucht wird. **Erforderlich** - ein leerer Wert wird abgelehnt. |
| `input/confidence-threshold` | `0.6` | Kleinster akzeptierter Score, 0 bis 1. |
| `input/nms-min-dist` | `0.0` | Mindestabstand in Pixeln zwischen zwei gemeldeten Treffern. |
| `input/pyramid` | `[1,2]` | Ebenen der Bildpyramide, auf denen die Suche läuft. Keine Geschwindigkeitseinstellung - siehe [Geschwindigkeit](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html#speed). |
| `input/result-coordinate` | `IMAGE` | `IMAGE` oder `CROP` - siehe unten. |
| `input/crop/*` | alle `0` | Zu durchsuchende Region; alles null durchsucht das ganze Bild. |
| `input/preprocess/bin-size` | `1` | Suche mit geringerer Auflösung: schneller, weniger präzise. Siehe [Bin-Größe](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html#bin-size). |
| `input/preprocess/blur-*` | aus | Optionale Glättung - siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html). |

## Ausführen

Setzen Sie die Eingaben und schreiben Sie dann auf `<module>/find-object/execute`:

```
module-1/find-object/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
module-1/find-object/input/object-id           = screw-m6
module-1/find-object/input/confidence-threshold = 0.7
module-1/find-object/input/nms-min-dist         = 40
write module-1/find-object/execute
```

Lesen Sie dann `output/status-code` und `output/result`.

> [!TIP]
> Setzen Sie `nms-min-dist` auf etwa die halbe Größe des Teils in Pixeln. Ohne diesen Wert wird ein einzelnes Teil oft mehrfach gemeldet, als Häufung leicht verschobener Treffer.

## Ein Objekt pro Suche

`input/object-id` nennt einen der Einträge auf `system/objects` und ist **erforderlich**: Ein leerer Wert wird mit Statuscode `-2` abgelehnt.

Es gibt keinen Durchlauf „nach allem suchen". Ein Detektor wird um ein Bild herum aufgebaut; die Suche nach mehreren Objekten bedeutet also mehrere Detektoren, und jeder verarbeitet das gesamte Bild erneut - das ist der teure Teil. `find-object` einmal pro Objekt auszuführen, macht diese Kosten sichtbar, statt sie hinter einer leeren Eingabe zu verstecken.

Um gemischte Teile zu sortieren, führen Sie die Methode einmal pro Objekt aus und vergleichen die Scores.

## Das Ergebnis

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

| Feld | Bedeutung |
| --- | --- |
| `matches[].x`, `.y` | Linke obere Ecke der gefundenen Vorlage, in Pixeln. |
| `matches[].width`, `.height` | Größe der Vorlage, die übereingestimmt hat, damit der Treffer gezeichnet werden kann. |
| `matches[].score` | Ähnlichkeit von 0.0 bis 1.0. |
| `matches[].object_id` | Das gefundene Objekt; bei jedem Treffer eines Durchlaufs dasselbe. |
| `best_index`, `best_score`, `best_object_id` | Der Treffer mit dem höchsten Score. |
| `image_width`, `image_height` | Der Bildausschnitt, in dem die Koordinaten liegen. |
| `confidence_threshold` | Der angewendete Schwellwert. |
| `timestamp` | Mikrosekunden seit Epoche, gesetzt beim Abschluss des Durchlaufs. |

Die Treffer sind nach Score sortiert, sodass `matches[0]` der beste ist.

Das Ergebnis enthält keine Rotation: Das gemeldete Rechteck ist achsenparallel. Wenn Sie wissen müssen, welche Orientierung gefunden wurde, geben Sie jeder Orientierung ein eigenes Objekt - `screw-m6-front`, `screw-m6-tilted` - und suchen Sie nacheinander danach. Die Antwort ist dann die `object_id`, die übereingestimmt hat.

## Bild- und Ausschnittskoordinaten

`input/result-coordinate` wählt das Bezugssystem, in dem Positionen gemessen werden:

- `IMAGE` (Standard) - das vollständige Bild an `input-image-address`. Das braucht ein Robotergriff.
- `CROP` - die durchsuchte Region, deren linke obere Ecke zu (0,0) wird.

`image_width` und `image_height` folgen derselben Wahl, sodass das Normieren einer Koordinate mit ihnen in beiden Fällen korrekt ist.

## Die Region wird genau wie angegeben durchsucht {#multiple-of-16}

Jede Größe funktioniert, und kein Teil von `input/crop` wird weggelassen. cv::linemod braucht zwar ein Bild, dessen Größe ein bestimmtes Vielfaches ist, aber der Detektor **füllt** intern bis dahin auf, statt eine ihm genehme Größe zu verlangen. Nichts, was Sie konfigurieren, muss also eine Regel erfüllen.

Früher wurde stattdessen beschnitten, was bis zu 7 Pixel am rechten und unteren Rand kostete - 31 bei `bin-size` 4. Das Beschneiden war schlimmer, als es aussah: Es verwarf Spalten, die die Kamera tatsächlich aufgenommen hatte, **und** ließ den toten Rand von cv::linemod - es ignoriert den äußeren Ring dessen, was es erhält - auf den verbliebenen Pixeln liegen. Gemessen erreichte ein Objekt an der letzten nutzbaren Position **0.79 beschnitten gegenüber 1.00 aufgefüllt**.

Die Auffüllung repliziert die Randpixel nach außen, erzeugt also keine eigenen Gradienten und kann nicht mit einer Form verwechselt werden; ein Treffer wird nie aus ihr heraus gemeldet. Sie wird nur rechts und unten angefügt, sodass jede gemeldete Position weiterhin eine Position im von Ihnen konfigurierten Bild ist.

## Was ein leeres Ergebnis bedeutet

Ein leeres Ergebnis mit `status-code` 1 bedeutet **das Objekt war nicht im Bild**, und nichts anderes.

Jeder andere Grund, aus dem eine Suche leer zurückkommen könnte - das Objekt hat kein Bild, das Bild ist unbrauchbar, eine Pyramidenebene ist ungültig, `bin-size` hat zu wenig vom Objekt zum Erkennen übrig gelassen - wird vor dem Start der Suche erkannt und als negativer Statuscode gemeldet. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execution-status.html).

## Erkennungsgeschwindigkeit

Das Bild wird bei der ersten Verwendung zu einem Detektor kompiliert, und dieser Detektor wird so lange wiederverwendet, wie Einstellungen und Objekt unverändert bleiben. Das Ändern einer Eingabe oder das Speichern einer neuen Vorlage baut ihn beim nächsten Durchlauf neu auf.

Das Kompilieren ist mit Abstand der teuerste Teil eines Durchlaufs. Eine Produktionsschleife, die wiederholt mit unveränderten Einstellungen ausführt, zahlt diese Kosten also einmal. Wer vor jedem Aufruf eine Einstellung ändert, zahlt sie jedes Mal.

Um die Suche selbst zu beschleunigen, verengen Sie zuerst `input/crop` und erhöhen dann `input/preprocess/bin-size`. `input/pyramid` zu erhöhen hilft **nicht** - siehe [Geschwindigkeit](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html#speed).

## Jedes Bild einer Kamera durchsuchen

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

# Objekte auf einem Bild-Stream finden (experimentell) – LumiScan Object Finder

URL: https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object` durchsucht ein Bild pro Aufruf: Ihr Programm setzt `input/input-image-address` und schreibt auf `execute`. Ein Bild-Stream funktioniert andersherum. Der Cam Driver veröffentlicht jedes Bild, das er aufnimmt, auf `<camera name>/control/publish/output/stream/frame`, mit seiner Größe, seinem Pixelformat und seiner Lineage (siehe das Handbuch des Cam Driver, *Bilder streamen*). Ein Modul abonniert den Stream einer Kamera, 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-object` durchsucht, wie sie in diesem Moment sind: das Objekt, der Konfidenz-Schwellwert, die Ausschnittsregion und jeder andere Knoten unter `find-object/input/`. Die eine 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 Bildes - welche Kamera es aufgenommen hat, in welchem Lauf des Kamera-Streams, als welches Bild des Laufs - ergänzt um den eigenen Schritt des Moduls. Siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 das neueste Bild, sobald die vorherige Suche abgeschlossen ist. 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-object-finder-de/1.1.0/lumiscan-object-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 die Art, wie ein Stream gestartet und gestoppt wird, 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 beim Object 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 Adressen unten beginnen mit `hdvisionsystems/lumiscan-object-finder/<module-id>/`. Sie liegen neben `find-object/`, nicht darin.

**Tabelle 1. Methoden**

| Adresse | Bedeutung |
| --- | --- |
| `control/subscribe/execute` | Prüft die fünf Eingaben von `control/subscribe` gemeinsam, speichert sie in der Einstellungsdatei des Moduls und wendet sie dann an: Ein laufender Stream folgt bei seinem nächsten Zyklus, ohne Neustart. Eine Eingabe allein zu schreiben ändert nichts. Siehe [Die Quelle wechseln](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die Quelle, die `control/unsubscribe/input/address` nennt, was auch den Stream-Modus beendet. Das Tag bleibt. 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 hinten in der Kette 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-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html#queue-size). |
| `control/subscribe/input/keep-latest-output` | bool | `true`, um jedes Stream-Ergebnis zusätzlich nach `find-object/output/result` zu schreiben. Siehe [Die letzte Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 davon ändern und ausführen kann.

Was die Quelle enthalten muss: Lesen Sie `hdvisionsystems/lumiscan-object-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-object-finder-de/1.1.0/lumiscan-object-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 `/` an einem der beiden Enden zählt nicht. |

**Tabelle 4. Einstellungen**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `setting/stream/enable`, `setting/stream/address`, `setting/stream/tag`, `setting/stream/queue-size`, `setting/stream/keep-latest-output` | wie die Eingaben | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat, 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-object-finder-de/1.1.0/lumiscan-object-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_object_matches` | Die in jedem Bild gefundenen Treffer und die Lineage des Bildes. Abonnieren Sie ihn, um jedes Ergebnis zu erhalten. Siehe [Das Ergebnis eines Bildes](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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. Es nennt die Quelle anhand ihrer Adresse, siehe [Das Ergebnis eines Bildes](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html#statistics). |

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

## Einrichten {#setting-up}

1. Stellen Sie sicher, dass der Stream des Cam Driver läuft: Sein `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active` ist `true`.
2. Setzen Sie die Eingaben von `find-object` wie für eine einzelne Suche, siehe [Ein Objekt finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html). Ein Aufruf von `find-object/execute` auf dem `output/image` der Kamera ist ein schneller Weg, sie zu prüfen.
3. Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, 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. Ab dann treffen die Ergebnisse ein.
6. Zum Stoppen setzen Sie `control/subscribe/input/enable` auf `false` und schreiben erneut auf `control/subscribe/execute`. Das gerade durchsuchte Bild wird zuerst fertiggestellt.

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

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

```none
krxclient write hdvisionsystems/lumiscan-object-finder/module-1/control/subscribe/input/address hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream
krxclient write hdvisionsystems/lumiscan-object-finder/module-1/control/subscribe/input/enable true
krxclient execute hdvisionsystems/lumiscan-object-finder/module-1/control/subscribe/execute
krxclient subscribe hdvisionsystems/lumiscan-object-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: 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 erhalten](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html#saving).

## Die Quelle wechseln {#subscribing}

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

1. Schreiben Sie die neuen Werte auf die Eingaben von `control/subscribe` - nur die, die Sie ändern: Die anderen enthalten, was angewendet ist.
2. Schreiben Sie auf `control/subscribe/execute`. Die Eingaben werden gemeinsam geprüft, in der Einstellungsdatei des Moduls gespeichert und erst dann angewendet: `setting/stream/` zeigt sie sofort, und ein laufender Stream folgt bei seinem nächsten Zyklus. Eine andere Adresse ersetzt die Quelle; die Bilder, die bei der alten warteten, werden als übersprungen gezählt. Ein neues Tag, eine neue Warteschlangengröße oder ein neues `keep-latest-output` braucht kein neues Abonnement: Ein neues Tag markiert das nächste Ergebnis.
3. Um die Quelle zu entfernen, schreiben Sie ihre Adresse 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 erhalten](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 Anwendungsprotokoll geschrieben.

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

## Das Ergebnis eines Bildes {#result}

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

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

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

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

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

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: object-id is empty - name the object to search for, see system/objects
```

Die Gründe sind dieselben, die `find-object` in seinem `status-text` nennt: eine Eingabe, die es ablehnen würde, ein Objekt, das nicht auf `system/objects` steht oder kein Bild hat, eine Ausschnittsregion, die nicht in das Bild passt, eine Region, die der Detektor nicht durchsuchen kann.

## Die Lineage eines Ergebnisses {#lineage}

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

1. Der Schritt der Kamera, wie der Cam Driver ihn erzeugt hat: `producer` ist die Adresse der Kamera, `hdvisionsystems/lumiscan-cam-driver/<camera name>`; `run`, wann der Stream der Kamera gestartet wurde; `sequence` die Nummer des Bildes in diesem Lauf; `external_id` die eigene Bildnummer der Kamera; `settings_hash` die Einstellungen der Kamera; `tag` das Tag des Cam Driver für die Kamera, standardmäßig deren Modul-ID, zum Beispiel `camera1`.
2. Der Schritt des Moduls: `producer` ist die Adresse des Moduls, `hdvisionsystems/lumiscan-object-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-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Bildes 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 wissen, von welcher Kamera ein Ergebnis kam, 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 sind oder verloren gingen.

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

Ein Bild, das keine Lineage trägt, liefert ein Ergebnis allein mit dem Schritt des Moduls. 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-object`, die die Suche liest, genau so, wie sie für das Bild gelesen wurde - alle außer `input/input-image-address`;
- das Bild des Objekts, anhand seines Inhalts: Ein neues Bild, das unter der alten Objekt-ID 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.

Der Stream vergleicht für jedes Bild den Inhalt des Objektbildes mit dem Bild, mit dem der Detektor des Moduls trainiert wurde. Unterscheiden sie sich, wird der Detektor neu trainiert, bevor das Bild durchsucht wird, sodass ein Ergebnis nie mit einem Bild erzeugt wird, das sein Hash nicht benennt. `find-object` allein vergleicht den Inhalt nicht: Es trainiert neu, wenn sich eine Detektoreinstellung ändert oder die Objektliste aktualisiert wird, siehe [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-storage.html).

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

```json
{
    "format": 1,
    "settings": {
        "find-object/input/confidence-threshold": 0.6,
        "find-object/input/object-id": "screw-m6",
        "find-object/template": {
            "file": "<object directory>/screw-m6.png",
            "fnv1a64": "<16 hex digits>"
        },
        "software.name": "lumiscan-object-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, sodass eine Änderung, die ein Ergebnis nicht verändert, trotzdem den Hash ändern kann.

## 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 ihre letzten Werte nach dem Stopp. 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 verdrängt, während ein Bild durchsucht wurde (siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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` nennt den Grund für das letzte, und das Protokoll benennt 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-object` gewartet hat. Teilen Sie durch `processed-frames` für den Mittelwert. |

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

## In der Einstellungsdatei erhalten {#saving}

Stream-Modus und Quelle sind Einstellungen des Moduls. Sie werden im Abschnitt `stream` der Einstellungsdatei des Moduls aufbewahrt, `<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 den Abschnitt `stream`; der Rest der Datei bleibt, wie er war. Das Modul legt die Datei an, wenn es noch keine gibt - ein Modul, dessen Eingaben nie gespeichert wurden, hat keine. `system/save-module-inputs` wiederum behält den Abschnitt `stream`, 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-object-finder` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-object-finder`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-obj-find\etc\lumiscan-object-finder` |

Der Abschnitt `stream`, neben den Eingaben von `find-object` (hier gekürzt):

```json
{
    "find-object": {
        "object-id": "screw-m6"
    },
    "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. Braucht 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 nach `find-object/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 ihn weg oder leer (`[]`). Ein Schritt startet das Modul außerhalb des Stream-Modus, mit einer Warnung im Protokoll; das Speichern behält ihn. |

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

Gut zu wissen:

- Die Datei wird einmal gelesen, wenn das Modul beim Start der Anwendung wiederhergestellt wird: ein Modul in der gespeicherten Modulliste oder `module-1` bei einer frischen Installation. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.
- Ein mit `system/create-module` angelegtes Modul beginnt mit ausgeschaltetem Stream, ohne Quelle, mit einer Warteschlangengröße von `1` und ausgeschaltetem `keep-latest-output`, was auch immer eine Datei seines Namens enthält. Was es von da an anwendet, wird in diese Datei gespeichert.
- Damit ein Modul und sein Stream nach einem Neustart zurückkommen, 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 damit seine Stream-Einstellungen. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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.
- Der Abschnitt `subscriptions` früherer Versionen wird nicht mehr gelesen, und das Modul protokolliert, dass er umgezogen ist: Geben Sie die Quelle als `address` an.

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

## 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, verdrängt das älteste davon, 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 alle 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 letzte Ausgabe behalten {#keep-latest-output}

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

## find-object, während der Stream läuft {#while-streaming}

Der Stream und `find-object` verwenden dieselben Eingaben und den einen trainierten Detektor des Moduls, und sie laufen auf einem Modul nie gleichzeitig:

- Ein Bild, das eintrifft, während `find-object` läuft, wartet, bis die Methode abgeschlossen ist. Es wird verzögert, nicht verworfen.
- Ein Aufruf von `find-object/execute`, während ein Bild durchsucht wird, antwortet mit busy: `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 busy-Aufruf (siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execute-a-method.html)). Bei einer streamenden Kamera passiert das oft. Stoppen Sie den Stream, bevor Sie die Methode aufrufen, oder rufen Sie sie erneut auf.
- `system/remove-module` antwortet ebenfalls mit busy (`-1`), während ein Bild dieses Moduls durchsucht wird. Stoppen Sie zuerst den Stream. Das Entfernen eines Moduls stoppt seinen Stream.
- `system/create-object` 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 wirken beim nächsten Start der Anwendung.
- 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 Object Finder

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

Die Standardwerte finden ein gut eingelerntes Objekt in einem vernünftigen Bild. Diese Seite beschreibt, was Sie ändern, wenn sie das nicht tun.

## Konfidenz-Schwellwert

`input/confidence-threshold` ist der kleinste Score, den ein Treffer erreichen muss, von 0 bis 1. Der Standardwert ist `0.6`.

Die Scores sind hier zwischen Durchläufen vergleichbar, also ist die praktische Methode das Messen statt des Ratens:

1. Setzen Sie den Schwellwert niedrig, auf `0.4`.
2. Führen Sie die Suche mit echten Teilen aus und sehen Sie sich die Scores in `output/result` an.
3. Setzen Sie den Schwellwert mit etwas Reserve unter den schlechtesten Score, den ein echtes Teil erzeugt.

Ein Schwellwert ab `0.9` lehnt in der Regel alles ab, auch gute Treffer.

## Doppelte Meldungen entfernen

`input/nms-min-dist` ist der Mindestabstand in Pixeln zwischen zwei gemeldeten Treffern. Fallen mehrere Treffer in diesen Abstand, wird nur der mit dem höchsten Score behalten.

Ohne diesen Wert wird ein einzelnes Teil häufig mehrfach gemeldet, als Häufung von Treffern wenige Pixel voneinander entfernt. Setzen Sie ihn auf etwa **die halbe Größe des Teils in Pixeln**. Der Standardwert `0` behält jeden Treffer, was nur dann sinnvoll ist, wenn Teile tatsächlich enger beieinanderliegen als ihre eigene Größe.

## Glättung

`input/preprocess/blur-sigma-x` wendet vor dem Matching eine Gauß-Glättung sowohl auf das Bild als auch auf das Bild des Objekts an. Sie ist **standardmäßig aus**.

Schalten Sie sie ein - beginnen Sie mit `1.0` -, wenn die Scores nahe am Schwellwert liegen oder die Bilder verrauscht sind. An realen Aufbauten gemessen, hebt die Glättung schwache Treffer spürbar an (etwa von 0.53 auf 0.60), während bereits starke Treffer ungefähr dort bleiben, wo sie waren. Genau deshalb ist sie standardmäßig aus: Sie hilft den Grenzfällen und tut nichts für die gesunden.

`blur-sigma-y` hat standardmäßig denselben Wert wie X. Die Kernelgrößen werden aus dem Sigma berechnet, sofern Sie sie nicht setzen; dann müssen sie ungerade sein. Alle werden ignoriert, solange `blur-sigma-x` 0 oder kleiner ist.

Die Glättung wird **vor** dem Binning angewendet, sodass ein Sigma eine Pixelzahl in Ihrem Originalbild bleibt und seine Bedeutung nicht ändert, wenn Sie `bin-size` ändern.

## Bin-Größe {#bin-size}

`input/preprocess/bin-size` verkleinert vor dem Matching sowohl das Bild als auch das Bild des Objekts um einen ganzzahligen Faktor. Der Standardwert ist `1`, was das Binning deaktiviert. **Das ist die Einstellung, die eine Suche schneller macht.**

Die Kosten eines Matchings skalieren mit der Pixelzahl, daher zahlt sich Binning stark aus. Gemessen an einem 1920x1080-Bild mit einem 128x128-Objekt, Mittelwert aus fünf Durchläufen:

| `bin-size` | Zeit | Bester Score | Im Vergleich zu 1 |
| --- | --- | --- | --- |
| `1` (Standard) | 49 ms | 1.00 | - |
| `2` | 8.4 ms | 1.00 | etwa 6x schneller |
| `4` | 3.5 ms | 0.94 | etwa 14x schneller |
| `8` | - | - | das Objekt wurde abgelehnt - nach dem Binning zu klein |

Was Sie aufgeben, ist **Präzision** - gemeldete Positionen werden auf `bin-size` Pixel quantisiert - und **Detail**. Binnen Sie weit genug, hat das Bild des Objekts die Kanten nicht mehr, auf die sich der Detektor stützt: Bei `bin-size` 8 wird ein 128x128-Objekt auf 16x16 reduziert, und der Detektor lehnt es ab. Das wird als fehlgeschlagener Durchlauf gemeldet, der das abgelehnte Objekt benennt, nie als leeres Ergebnis, sodass es nicht mit einem fehlenden Teil verwechselt werden kann.

Positionen in `output/result` sind immer in den Pixeln des Bildes, das Sie konfiguriert haben - die Anwendung rechnet sie zurück -, sodass eine höhere `bin-size` nichts daran ändert, wie Sie das Ergebnis lesen.

Kleine Objekte erreichen diese Grenze früher als große. Erhöhen Sie `bin-size` schrittweise und beobachten Sie die Scores: Wenn sie Richtung Schwellwert zu fallen beginnen, sind Sie einen Schritt zu weit gegangen.

`bin-size` kostet Sie an den Rändern der Region nichts: Sie wird unabhängig vom Binning genau wie konfiguriert durchsucht - siehe [Die Region wird genau wie angegeben durchsucht](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html#multiple-of-16).

## Pyramidenebenen

`input/pyramid` listet die Ebenen der Bildpyramide, auf denen die Suche läuft, Standard `[1,2]`. Größere Werte machen die Erkennung toleranter, aber gröber.

> [!NOTE]
> **Das ist keine Geschwindigkeitseinstellung**, auch wenn sie so klingt. Tiefere Pyramiden waren gemessen etwas *langsamer*, nicht schneller - `[1,2]` 47 ms, `[2,4]` 50 ms, `[4,8]` 51 ms auf demselben Bild -, weil die Arbeit des Detektors pro Ebene etwa so schnell wächst, wie seine Arbeit pro Pixel schrumpft. Verwenden Sie `bin-size` für Geschwindigkeit und `pyramid` für Toleranz.

Welche Ebenen gültig sind, hängt von der Bildgröße ab, und es gibt keine allgemeine Regel. Eine ungültige Kombination wird als fehlgeschlagener Durchlauf mit negativem Statuscode gemeldet, statt geraten zu werden. Ändern Sie sie daher in kleinen Schritten und prüfen Sie den Status.

## Den Bereich einschränken

`input/crop/{startX, startY, width, height}` beschränkt die Suche auf einen Teil des Bildes. Eine Breite oder Höhe von null reicht bis zum entsprechenden Rand. Die Standardregion aus lauter Nullen durchsucht also alles, und `startX=100` mit Nullgrößen sucht von dort bis zur rechten unteren Ecke.

Zwei Gründe, sie zu verwenden: Geschwindigkeit, weil eine kleinere Region schneller durchsucht wird, und Zuverlässigkeit, weil das Ausschließen von Bereichen, in denen das Teil nicht sein kann, Fehltreffer auf ähnlich aussehendem Hintergrund vermeidet.

Das ist das erste Mittel, wenn eine Suche zu langsam ist, denn anders als `bin-size` kostet es keinerlei Präzision.

Die Region wird genau so durchsucht, wie Sie sie setzen - siehe [Die Region wird genau wie angegeben durchsucht](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html#multiple-of-16).

## Ansichten hinzufügen statt abzustimmen

Wird ein Objekt in **bestimmten Orientierungen** verfehlt, während es in anderen zuverlässig gefunden wird, hilft keine Einstellung auf dieser Seite. Der Detektor dreht Vorlagen nicht - lernen Sie eine weitere Ansicht in der verfehlten Orientierung ein. Siehe [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html).

Ebenso: Wird das Objekt verfehlt, wenn es näher an der Kamera oder weiter von ihr entfernt liegt, lernen Sie eine Ansicht in diesem Abstand ein.

## Geschwindigkeit {#speed}

Die Reihenfolge, in der Sie vorgehen sollten:

1. **Den Bereich einschränken** mit `input/crop`. Das kostet keine Präzision und kommt daher immer zuerst.
2. **`input/preprocess/bin-size` erhöhen**, auf Kosten von Präzision und feinen Details. Auf einem Full-HD-Bild bringt das etwa 6x bei `2` und 14x bei `4`.
3. **Nach weniger Objekten suchen.** Jedes `execute` sucht nach einem Objekt und verarbeitet das ganze Bild erneut; ein Objekt wegzulassen, das Sie nicht brauchen, spart also einen ganzen Durchlauf.

`input/pyramid` zu erhöhen steht **nicht** auf dieser Liste: Gemessen ist es etwas langsamer statt schneller.

Halten Sie die Einstellungen zwischen Durchläufen stabil. Der Detektor wird beim ersten Durchlauf aus dem Bild des Objekts kompiliert und wiederverwendet, solange sich nichts ändert; das Ändern einer Eingabe baut ihn neu auf, und der Neuaufbau kostet weit mehr als eine Erkennung.

# Objektspeicher – LumiScan Object Finder

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

## Eine Datei pro Objekt

Ein Objekt **ist** sein Bild: eine `.png`-Datei auf der obersten Ebene des Objektverzeichnisses, benannt nach dem Objekt.

```
<configuration directory>/objects/
├── screw-m6.png
└── bracket.png
```

was die Anwendung veröffentlicht als

```
system/objects = ["bracket", "screw-m6"]
```

Es gibt keine zweite Liste, weil es nichts anderes aufzulisten gibt - die Objekt-ID und das Bild sind dasselbe. Ein Detektor wird um genau ein Bild herum aufgebaut, sodass eine zweite Ansicht eines Objekts nirgends hingehört: Ein Objekt, das in zwei Orientierungen erkannt werden muss, ist zwei Objekte, `screw-m6-front` und `screw-m6-tilted`, nach denen nacheinander gesucht wird.

Alles, was keine `.png`-Datei auf der obersten Ebene des Verzeichnisses ist, wird übersprungen, Unterverzeichnisse eingeschlossen.

Nur kleingeschriebenes `.png` wird aufgelistet. `.PNG` wird bewusst ignoriert: Ein Abgleich ohne Berücksichtigung der Groß-/Kleinschreibung ließe `screw.png` und `screw.PNG` zu einem Eintrag zusammenfallen, und die Liste würde nicht mehr sagen, auf welche Datei ein Name verweist.

## Objekte auf das Gerät bringen

Entweder lernen Sie sie mit [create-object](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html) von der Kamera ein, oder Sie legen `.png`-Dateien in der obigen Struktur in das Konfigurationsverzeichnis der Anwendung: auf ctrlX OS hochladen, auf einem PC hineinkopieren. Das Konfigurationsverzeichnis und sein Standardordner `objects` werden beim Start angelegt, sodass es direkt nach der Installation einen Ort dafür gibt.

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

## Das Verzeichnis wechseln

`system/object-dir` nennt das verwendete Verzeichnis. Es ist **schreibgeschützt**, und `system/set-object-dir` ist das Einzige, was es ändert:

```
system/set-object-dir/input/object-dir = production-parts
write system/set-object-dir/execute
```

Die Methode prüft zuerst und veröffentlicht `object-dir` und `objects` gemeinsam, sodass ein abgelehnter Aufruf beide genau so lässt, wie sie waren, und die Listen immer das tatsächlich verwendete Verzeichnis beschreiben. Die Wahl wird gespeichert und übersteht einen Neustart.

Das Verzeichnis muss im Konfigurationsverzeichnis bereits existieren. Es wird bewusst nicht für Sie angelegt: Das Standardverzeichnis wird beim Start erzeugt, ein fehlendes bedeutet also einen Tippfehler, und das stille Anlegen eines leeren Ordners würde ihn verbergen.

> [!NOTE]
> Der Data Layer erzwingt den Schreibschutz der eigenen Knoten einer Anwendung nicht. Ein Client, der direkt auf `system/object-dir` schreibt, ändert also den angezeigten Wert. Er ändert **nicht**, welches Verzeichnis die Anwendung liest, und die Listen beschreiben dann einen anderen Ordner, als der Knoten behauptet. Verwenden Sie `set-object-dir`.

## Pfadregeln

`object-dir` und `object-id` werden beide relativ zum Konfigurationsverzeichnis interpretiert. Absolute Pfade und jeder Pfad, der mit `..` hinausführt, werden mit Status `-2` abgelehnt. Die Anwendung kann Vorlagen daher nur innerhalb ihres eigenen Konfigurationsbereichs lesen und schreiben, was auch immer ein Client verlangt.

## Wann Änderungen bemerkt werden

`system/objects` wird beim Start aktualisiert, wenn `set-object-dir` das Verzeichnis wechselt und wenn `create-object` eine Vorlage speichert.

Dateien, die auf anderem Weg hinzugefügt oder entfernt werden - ein Upload oder eine SSH-Sitzung auf ctrlX OS, auf einem PC von Hand hineinkopierte oder gelöschte Dateien -, werden beim nächsten dieser Ereignisse oder beim nächsten Neustart übernommen. Jede Aktualisierung lässt außerdem jedes Modul seinen Detektor neu aufbauen, sodass eine vom Datenträger entfernte Vorlage nicht mehr gefunden werden kann.

# Modulverwaltung – LumiScan Object Finder

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

Ein **Modul** ist eine konfigurierte Instanz der Anwendung. Es besitzt die Matching-Operation mit eigenen Einstellungen und Ergebnissen:

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

Das Anlegen einer Vorlage ist **nicht** modulbezogen: Es schreibt in das eine Verzeichnis, das alle Module teilen, und liegt daher auf dem System-Knoten als `system/create-object`. Siehe [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html).

Module können angelegt und entfernt werden, während die Anwendung läuft. Eine frische Installation bedient ein Modul 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-object-finder/system/
```

## Knoten

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `modules` | string array | Die derzeit vorhandenen Module |
| `create-object/execute` | Methode | Schneidet eine Vorlage aus einem Live-Bild aus und speichert sie in `object-dir`, zur Verwendung durch jedes Modul. Siehe [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.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 dieselben Module beim nächsten Start erneut 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 |

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, ob `system/create-module/output/status-code` `1` ist

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

Das Entfernen eines Moduls ist das Spiegelbild, über `remove-module`. Ein Modul wird mit `-1` (busy) 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 Standardeingabewerten, auch wenn vorher ein Modul dieses Namens existierte und seine Einstellungen gespeichert wurden. Diese Einstellungen bleiben auf dem Datenträger, bis das Entfernen dauerhaft gemacht wird - `save-current-modules` löscht die gespeicherten Eingaben jedes Moduls, das die neue Liste nicht mehr nennt, denn bis die Liste geschrieben ist, ist ein Entfernen nicht dauerhaft, und ein Neustart bringt das Modul mit intakten 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 erneut angelegt werden;
- **die Einstellungen jedes Moduls** - `save-module-inputs`, einmal pro Modul.

So speichern Sie die Einstellungen eines Moduls:

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

Jede Eingabe dieses Moduls wird in das Konfigurationsverzeichnis der Anwendung geschrieben und beim nächsten Start wiederhergestellt. Ergebnisse werden nicht gespeichert - sie werden vom nächsten Durchlauf erzeugt. Die Bild-Stream-Einstellungen eines Moduls werden in derselben Datei gespeichert, durch die eigenen Methoden des Streams - siehe [In der Einstellungsdatei erhalten](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 Modul ein Modul enthält

Die Ebene `<module-id>` ist immer vorhanden, sodass sich Adressen nicht ändern, wenn ein zweites Modul hinzukommt: Ein heute gegen `module-1` geschriebenes Programm funktioniert weiter. Das entspricht auch der Pfadkonvention, die die anderen LumiScan-Anwendungen dokumentieren, 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, AI Object Matching und Calibration unterscheiden, ist in [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html#registry-apps) zusammengefasst.

## Was zwischen Modulen geteilt wird

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

# Data-Layer-Referenz – LumiScan Object Finder

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

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).

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

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

Von Anfang bis Ende: ein Teil von einer Live-Kamera einlernen, es finden und die Einstellungen so sichern, dass sie einen Neustart überstehen.

## Bevor Sie beginnen

- LumiScan Cam Driver ist auf demselben Gerät installiert und veröffentlicht ein Bild, zum Beispiel unter `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- LumiScan Object Finder ist installiert - auf ctrlX OS auch lizenziert -, und `system/modules` listet `module-1`.
- Das Teil liegt vor der Kamera, in der Beleuchtung, die die Installation tatsächlich verwenden wird.

## Schritt 1: Die erste Ansicht einlernen

Sehen Sie sich das Live-Bild an und notieren Sie das Pixelrechteck, das das Teil einnimmt - auf ctrlX OS zeigt die ctrlX-Weboberfläche das Bild - oder lesen Sie `width` und `height` vom Bildknoten.

Setzen Sie die Eingaben und führen Sie aus:

```
system/create-object/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
system/create-object/input/object-id           = screw-m6
system/create-object/input/crop/startX         = 820
system/create-object/input/crop/startY         = 400
system/create-object/input/crop/width          = 160
system/create-object/input/crop/height         = 120
write system/create-object/execute
```

Prüfen Sie, ob `system/create-object/output/status-code` `1` ist und `output/object-path` die Datei nennt. `system/objects` sollte jetzt `screw-m6` enthalten.

Schneiden Sie eng aus. Hintergrund innerhalb der Vorlage ist Hintergrund, den der Detektor zu sehen erwartet.

## Schritt 2: Die anderen Orientierungen einlernen

Der Detektor dreht ein Bild nicht. Jede Orientierung, in der das Teil ankommt, braucht daher ein eigenes **Objekt**. Wiederholen Sie Schritt 1 mit einer anderen `object-id` - etwa `screw-m6-tilted` - und suchen Sie in einem eigenen Durchlauf danach.

Kommt das Teil immer nur in einer Lage an, genügt ein Objekt.

## Schritt 3: Das Teil finden

```
module-1/find-object/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
module-1/find-object/input/object-id           = screw-m6
module-1/find-object/input/nms-min-dist        = 40
write module-1/find-object/execute
```

Lesen Sie `module-1/find-object/output/status-code`. `1` bedeutet, dass der Durchlauf abgeschlossen wurde; lesen Sie dann `output/result`.

`nms-min-dist` bei etwa der halben Größe des Teils in Pixeln verhindert, dass ein Teil als Häufung von Treffern gemeldet wird.

## Schritt 4: Den Schwellwert anhand echter Teile setzen

Führen Sie Schritt 3 mehrmals mit echten Teilen aus und notieren Sie den `score` der echten Treffer. Setzen Sie dann

```
module-1/find-object/input/confidence-threshold = <a little below the worst genuine score>
```

Liegen die echten Scores nahe am Schwellwert, schalten Sie die Glättung ein - setzen Sie `module-1/find-object/input/preprocess/blur-sigma-x` auf `1.0` - und messen Sie erneut. Siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html).

## Schritt 5: Dauerhaft machen

Einstellungen wirken sofort, werden aber erst gespeichert, wenn Sie es verlangen:

```
system/save-module-inputs/input/module-id = module-1
write system/save-module-inputs/execute
write system/save-current-modules/execute
```

Beide sollten Status `1` melden. Das Modul und seine Einstellungen kommen jetzt nach einem Neustart zurück.

## Schritt 6: Aus einem Steuerungsprogramm ausführen

Pro Zyklus:

1. Schreiben Sie auf `module-1/find-object/execute`.
2. Lesen Sie `module-1/find-object/output/status-code`.
3. Ist er negativ, ist der Durchlauf fehlgeschlagen - lesen Sie `output/status-text` für den Grund und verwenden Sie das Ergebnis nicht.
4. Ist er `1`, lesen Sie `output/result`. Eine leere `matches`-Liste bedeutet, dass das Teil nicht da war.

Lesen Sie die Ausgaben, **bevor** Sie das nächste `execute` auslösen: Ein Durchlauf leert sie beim Start.

Wie jedes Bild der Kamera ohne einen Aufruf pro Bild durchsucht wird, lesen Sie in [Objekte auf einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html).

## Wenn das Teil nicht gefunden wird

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

- [Das Ergebnis ist leer, obwohl der Statuscode `1` ist](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-empty-result) - Scores knapp unter dem Schwellwert, ein Teil, das nur in manchen Orientierungen oder Arbeitsabständen gefunden wird, oder nie gefunden wird
- [Ein Teil wird mehrfach gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-duplicate-matches)
- [Statuscodes und Fehlermeldungen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-status-codes) - wenn `status-code` negativ ist

# FAQ – LumiScan Object Finder

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

Kurze Antworten auf häufige Fragen zu LumiScan Object 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-object-finder-de/1.1.0/troubleshooting.html) beschrieben.

## Voraussetzungen und Einrichtung

### Auf welchen Plattformen läuft der Object 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, sodass ein für den einen geschriebenes Programm auch mit dem anderen funktioniert. 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-object-finder-de/1.1.0/lumiscan-object-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 braucht der Object Finder? {#faq-image-source}

- **Antwort:** Die Anwendung kommuniziert nicht selbst mit einer Kamera. Sie liest den Bildknoten einer anderen Anwendung, die auf **demselben Gerät** läuft - demselben ctrlX CORE oder 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 funktioniert, wenn ihr Bildknoten `data` (rohe, unkomprimierte uint8-Pixeldaten), `width`, `height` und `pixel-type` (Name des GenICam-Pixelformats) bereitstellt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/requirements.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. Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/requirements.html)

## Objekte einlernen

### Wie lerne ich ein Objekt von der Live-Kamera ein? {#faq-create-object}

- **Antwort:** Verwenden Sie `system/create-object`; es ist anwendungsweit, sodass ein einmal eingelerntes Objekt von jedem Modul gefunden werden kann:
  - Legen Sie das Teil vor die Kamera, in der Beleuchtung, die die Installation verwenden wird.
  - Setzen Sie `system/create-object/input/input-image-address`, `input/object-id` (zum Beispiel `screw-m6`) und `input/crop/startX`, `startY`, `width`, `height` (Breite und Höhe größer als 0).
  - Schreiben Sie auf `system/create-object/execute` und prüfen Sie, ob `output/status-code` `1` ist.
  - Das Bild wird als `<object-id>.png` gespeichert, `output/object-path` nennt die Datei, und `system/objects` listet das neue Objekt. Ein bestehendes Objekt mit derselben ID wird überschrieben.
- **Mehr:** [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html), [Anleitung: Ein Teil in einem Kamerabild finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/how-tos/find-a-part-from-a-camera-image.html)

### Wie eng soll ich beim Einlernen eines Objekts ausschneiden? {#faq-crop-margin}

- **Antwort:** Lassen Sie etwa 5 Pixel Hintergrund um das Teil; mehr bringt nichts. Ein Ausschnitt, der an der Silhouette endet, verbirgt die Kontur vor dem Detektor: Das Objekt wird entweder als fehlgeschlagener Durchlauf abgelehnt, der es benennt, oder angenommen, aber nur auf die inneren Details des Teils gestützt. Ein zu weiter Ausschnitt, der eine Werkbankkante oder ein benachbartes Teil einschließt, macht das Matching weniger zuverlässig, denn Hintergrund im Bild ist Hintergrund, den der Detektor dann zu sehen erwartet.
- **Mehr:** [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html)

### Wie wechsle ich zu einem anderen Objektverzeichnis? {#faq-object-dir}

- **Antwort:** Schreiben Sie `system/set-object-dir/input/object-dir` und schreiben Sie auf `system/set-object-dir/execute`. Schreiben Sie nicht direkt auf `system/object-dir`: Das ändert den angezeigten Wert, aber nicht das Verzeichnis, das die Anwendung liest. Das Verzeichnis muss im Konfigurationsverzeichnis bereits existieren; absolute Pfade und Pfade, die mit `..` hinausführen, werden mit Status `-2` abgelehnt. Ein abgelehnter Aufruf ändert nichts, und die Wahl wird gespeichert.
- **Mehr:** [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-storage.html)

## Finden und Abstimmen

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

- **Antwort:** Setzen Sie `<module>/find-object/input/input-image-address` und `input/object-id`, schreiben Sie auf `<module>/find-object/execute` (ein blockierender Aufruf) und lesen Sie `output/status-code`. `input/object-id` ist erforderlich: Ein leerer Wert wird mit `-2` abgelehnt. Jeder Durchlauf sucht nach einem Objekt; um gemischte Teile zu sortieren, führen Sie ihn einmal pro Objekt aus und vergleichen die Scores. Bei `1` lesen Sie `output/result`: `matches` ist nach Score sortiert, sodass `matches[0]` der beste ist. Jeder Treffer liefert die linke obere Ecke `x`, `y`, `width` und `height` der Vorlage, die übereingestimmt hat, den `score` (0 bis 1) und die `object_id`. Das Rechteck ist achsenparallel; das Ergebnis enthält keine Rotation.
- **Mehr:** [Ein Objekt finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html)

### Wie wähle ich den Konfidenz-Schwellwert? {#faq-confidence-threshold}

- **Antwort:** Messen statt raten. Setzen Sie `input/confidence-threshold` niedrig (`0.4`), führen Sie die Suche mit echten Teilen aus, notieren Sie die Scores in `output/result` und setzen Sie den Schwellwert etwas unter den schlechtesten Score, den ein echtes Teil erzeugt. Der Standardwert ist `0.6`; ein Schwellwert ab `0.9` lehnt in der Regel alles ab. Liegen die echten Scores nahe am Schwellwert oder sind die Bilder verrauscht, setzen Sie `input/preprocess/blur-sigma-x` auf `1.0` (die Glättung ist standardmäßig aus) und messen Sie erneut.
- **Mehr:** [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html)

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

- **Antwort:**
  - Schränken Sie den Bereich mit `input/crop` ein; das kostet keine Präzision.
  - Erhöhen Sie `input/preprocess/bin-size`. Auf einem 1920x1080-Bild mit einem 128x128-Objekt war `2` gemessen etwa 6x und `4` etwa 14x schneller. Positionen werden auf `bin-size` Pixel quantisiert, und ein zu weit gebinntes Objekt wird abgelehnt.
  - Suchen Sie nach weniger Objekten; jedes `execute` verarbeitet das ganze Bild erneut.
  - Halten Sie die Einstellungen zwischen Durchläufen stabil: Der Detektor wird beim ersten Durchlauf kompiliert und bei jeder Änderung einer Eingabe neu aufgebaut, was weit mehr kostet als eine Erkennung.
  - `input/pyramid` zu erhöhen macht die Suche nicht schneller; gemessen ist sie etwas langsamer.
- **Mehr:** [Die Suche abstimmen: Geschwindigkeit](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html#speed)

### Kann der Object 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-object` (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`. `enable` allein 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, sodass ein Modul, das gestreamt hat, nach einem Neustart wieder streamt. Für eine SPS schalten Sie `control/subscribe/input/keep-latest-output` ein und lesen `find-object/output/result`.
- **Mehr:** [Objekte auf einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/processing-an-image-stream.html), [Streams (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)

## Statuscodes und Fehler

### Woher weiß ich, ob eine Operation funktioniert hat, und wo steht der Grund für einen Fehler? {#faq-status-codes}

- **Antwort:** Prüfen Sie das Vorzeichen von `output/status-code`: größer als 0 ist Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht gelaufen ist, kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat. Der Grund steht auf `output/status-text`, der mit `ok:` oder `error:` beginnt; ungültige Eingaben werden gemeinsam gemeldet, jede mit Nennung der Eingabe und ihres Werts. Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST ein bloßes `400`), lesen Sie also anschließend `output/status-text`; der Text steht auch im Anwendungsprotokoll: auf ctrlX OS im ctrlX Logbook oder mit `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung. `-1` (busy) bedeutet, dass eine andere Operation desselben Moduls noch lief; es wurde nichts getan.
- **Mehr:** [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execute-a-method.html), [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execution-status.html)

## Fehlerbehebung {#troubleshooting}

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

- [Statuscode `-1` (busy)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-busy-while-streaming)
- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-status-minus-2)
- [Statuscode `-3` (Bild lesen fehlgeschlagen)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-status-minus-3)
- [Statuscode `-4` (Quelle nicht gefunden)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-status-minus-4)
- [Die Ausschnittsregion passt nicht in das Bild](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-crop-does-not-fit)
- [Der Durchlauf schlägt fehl und benennt das Objekt](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-object-refused-bin-size)
- [Statuscode `-6` (Schreiben fehlgeschlagen)](https://docs.hdvisionsystems.com/de/lumiscan-object-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-object-finder-de/1.1.0/troubleshooting.html#faq-empty-result)
- [Ein Teil wird mehrfach gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-duplicate-matches)
- [`output/result` ist leer, obwohl die Suche eben noch funktioniert hat](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-result-empty-next-run)
- [Eine hochgeladene `.png`-Datei erscheint nicht auf `system/objects`](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-object-not-listed)
- [Der Bild-Stream liefert keine Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-stream-no-results)
- [Meine Einstellungen oder Module sind nach einem Neustart verschwunden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-settings-lost)
- [Die Anwendung beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-app-stops-after-start)
- [Statuscode `-11` (Lizenz nicht verfügbar)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#ts-licence-unavailable)

## Module, Lizenzierung und Support

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

- **Antwort:** Eine Lizenz deckt zehn Module ab; das elfte Modul belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz auf dem Gerät es abdeckt. Bezugswege:
  - Bei HD Vision Systems gekauft: Die Lizenz ist auf einem LumiScan Key (Windows 11 oder Ubuntu 24.04). Pro Gerät, auf dem die Software gleichzeitig läuft, ist ein LumiScan Key nötig; Keys können zwischen Geräten getauscht werden.
  - Im ctrlX Store für Windows 11 gekauft: ctrlX WORKS plus ein LumiScan Key.
  - Im ctrlX Store für ctrlX OS (ctrlX CORE oder IPC) gekauft: eine ctrlX-Lizenz, kein Key.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/requirements.html#licence), [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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 bekomme Support? {#faq-support}

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

# Fehlerbehebung – LumiScan Object Finder

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

Diese Seite beschreibt Probleme und Fehlermeldungen von LumiScan Object Finder, nach Kategorien geordnet. Beginnen Sie mit den [allgemeinen Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-object-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 gelaufen ist, 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-object-finder-de/1.1.0/lumiscan-object-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 Anwendungsprotokoll.** 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-object-finder.json` fest (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` oder `OFF`). Der Wert wird beim Start gelesen; starten Sie die Anwendung nach einer Änderung also neu. Siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/datalayer-reference.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-object-finder-de/1.1.0/troubleshooting.html#ts-app-stops-after-start).

Das Konfigurationsverzeichnis enthält `lumiscan-object-finder.json`, die Moduldateien `<module-id>.json`, die Objekte und `settings-history/`:

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

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

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

**Symptome**

`output/status-code` von `find-object` 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 oft. Auch `system/remove-module` kann mit `-1` (busy) 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-object` 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-object/output/result`.

- **Wenn `system/remove-module` mit busy 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-object-finder-de/1.1.0/lumiscan-object-finder/execute-a-method.html) und [find-object, während der Stream läuft](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-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) {#ts-status-minus-2}

**Symptome**

`output/status-code` ist `-2`. `output/status-text` beginnt mit `error:` und nennt jede Eingabe, die nicht verwendet werden kann, zusammen mit ihrem Wert. Alle ungültigen Eingaben werden gemeinsam gemeldet.

**Mögliche Ursachen**

- Eine erforderliche Eingabe ist leer. `input/object-id` von `find-object` ist erforderlich.
- Die Bildadresse zeigt auf diese Anwendung selbst.
- `input/object-id` von `system/create-object` oder `input/object-dir` von `system/set-object-dir` ist ein absoluter Pfad oder ein Pfad, der mit `..` aus dem Konfigurationsverzeichnis hinausführt.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt die fehlerhafte Eingabe und ihren Wert.
2. Lesen Sie das Anwendungsprotokoll. Jede ungültige Eingabe hat eine eigene Warnzeile.

**Lösung**

- **Wenn eine erforderliche Eingabe leer ist:** Setzen Sie sie. Für `find-object` setzen Sie `input/object-id` auf einen Eintrag von `system/objects`.
- **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, zum Beispiel `production-parts`.

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

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-object-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 lesen fehlgeschlagen) {#faq-status-minus-3}

**Symptome**

`output/status-code` von `find-object` oder `system/create-object` 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.
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-object-finder-de/1.1.0/lumiscan-object-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-object-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-object` ist `-4`.

**Mögliche Ursachen**

- Das Bild des Objekts fehlt oder ist nicht lesbar: `input/object-id` nennt keinen Eintrag von `system/objects`.
- Das Objektverzeichnis fehlt oder ist nicht lesbar.
- Das Bild liegt in einem anderen Verzeichnis als dem verwendeten.

**Diagnose**

1. Vergleichen Sie `input/object-id` mit `system/objects`. Erwartet: Die ID ist aufgeführt, in derselben Schreibweise.
2. Lesen Sie `system/object-dir`. Erwartet: Es nennt das Verzeichnis, das die `.png`-Datei des Objekts enthält.
3. Prüfen Sie die Datei in diesem Verzeichnis. Erwartet: eine kleingeschriebene `.png`-Datei auf der obersten Ebene des Verzeichnisses, nach dem Objekt benannt.

**Lösung**

- **Wenn die Objekt-ID nicht aufgeführt ist:** Korrigieren Sie `input/object-id`, oder lernen Sie das Objekt mit `system/create-object` ein. Eine Datei, die Sie auf anderem Weg in das Verzeichnis legen, wird erst nach einer Aktualisierung aufgeführt, siehe [Problem: Eine hochgeladene `.png`-Datei erscheint nicht auf `system/objects`](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#faq-object-not-listed).
- **Wenn das Verzeichnis nicht das erwartete ist:** Wechseln Sie mit `system/set-object-dir`, siehe [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-storage.html).

Führen Sie `find-object` 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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`, `input/object-id`, `system/object-dir` und `system/objects`.

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

**Symptome**

`system/create-object` antwortet mit Status `-5` (ungültige Ausschnittsregion), und `output/status-text` nennt den Rand und die Bildgröße, zum Beispiel:

```
error: Crop region does not fit inside the 1920x1080 image: crop/startY + crop/height (1000 + 200 = 1200) exceeds the image height 1080
```

Bei `find-object` nennt `output/status-text` die Eingabe und die Grenze, die sie verletzt hat, zum Beispiel `error: crop/startX + crop/width (100 + 900 = 1000) 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. Der gesamte Ausschnitt muss innerhalb des Bildes liegen; er wird abgelehnt, nicht beschnitten.
- Bei `system/create-object` 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.

**Lösung**

- **Wenn die Region über einen Rand hinausreicht:** Korrigieren Sie `input/crop/startX`, `startY`, `width` oder `height`, sodass die Region in die in der Meldung genannte Bildgröße passt.
- **Wenn Breite oder Höhe 0 ist (`create-object`):** 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 [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-object-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: Der Durchlauf schlägt fehl und benennt das Objekt {#faq-object-refused-bin-size}

**Symptome**

`find-object` schlägt mit einem negativen Statuscode fehl, und `output/status-text` benennt das Objekt. Das geschieht oft, nachdem `input/preprocess/bin-size` erhöht wurde. Es wird nie als leeres Ergebnis gemeldet.

**Mögliche Ursachen**

- Das Objekt ist zu weit gebinnt. Sein Bild hat dann die Kanten nicht mehr, auf die sich der Detektor stützt, und der Detektor lehnt es ab, zum Beispiel ein 128x128-Objekt bei `bin-size` 8 (auf 16x16 verkleinert). Kleine Objekte erreichen diese Grenze früher als große.
- Das Bild wurde beim Einlernen entlang der Silhouette des Teils ausgeschnitten. Ein Bild muss eine Mindestzahl starker Gradientenpunkte liefern, und ein Ausschnitt, der an der Silhouette endet, verbirgt die Kontur vor dem Detektor.

**Diagnose**

1. Lesen Sie `input/preprocess/bin-size` des Moduls. Senken Sie den Wert um eine Stufe und führen Sie `find-object` erneut aus. Erwartet: `output/status-code` ist `1`.
2. Schlägt der Durchlauf auch bei `bin-size` `1` fehl, öffnen Sie die `.png`-Datei des Objekts im Objektverzeichnis. Erwartet: ein dünnes, gleichmäßiges Band Hintergrund von etwa 5 Pixeln um das Teil.

**Lösung**

- **Wenn das Objekt zu weit gebinnt ist:** Senken Sie `input/preprocess/bin-size` wieder. Erhöhen Sie den Wert schrittweise und hören Sie auf, wenn die Scores Richtung Schwellwert zu fallen beginnen.
- **Wenn das Bild an der Silhouette ausgeschnitten wurde:** Lernen Sie das Objekt mit `system/create-object` erneut ein, mit etwa 5 Pixeln Hintergrund um das Teil. Siehe [Ein Objekt anlegen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/creating-an-object.html).

Siehe [Die Suche abstimmen: Bin-Größe](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/tuning-the-search.html#bin-size).

**Wenn das Problem weiterhin besteht**

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

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

**Symptome**

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

**Mögliche Ursachen**

- Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt die Datei, die nicht geschrieben werden konnte.
2. Lesen Sie das Anwendungsprotokoll zum Zeitpunkt des Aufrufs.
3. Prüfen Sie das Konfigurationsverzeichnis (siehe [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#general-checks)). Erwartet: Es existiert, und die Anwendung kann hineinschreiben.

**Lösung**

- **Wenn es ein Berechtigungsproblem ist:** Machen Sie das Konfigurationsverzeichnis 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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`.

## Suchergebnisse {#ts-results}

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

**Symptome**

`output/status-code` von `find-object` ist `1`, aber `matches` in `output/result` ist leer (`best_score` `0.0`, `best_object_id` leer). Oder ein echtes Teil wird in manchen Bildern gefunden und in anderen verfehlt: nur in manchen Orientierungen oder nur in manchen Arbeitsabständen.

**Mögliche Ursachen**

Ein leeres Ergebnis mit Statuscode `1` bedeutet, dass das Objekt nicht im durchsuchten Bild war, und nichts anderes. Jeder andere Grund - fehlendes Bild des Objekts, unbrauchbares Bild, ungültige Pyramidenebene, `bin-size` lässt zu wenig vom Objekt übrig - wird als negativer Statuscode gemeldet. Wird ein echtes Teil verfehlt:

- `input/crop` schließt das Teil aus.
- Die Scores der echten Teile liegen unter `input/confidence-threshold` (Standard `0.6`). Ein Schwellwert ab `0.9` lehnt in der Regel alles ab.
- Das Teil kommt in einer Orientierung an, für die kein Objekt eingelernt wurde. Der Detektor dreht kein Bild.
- Das Teil liegt näher an der Kamera oder weiter von ihr entfernt als in dem Bild, aus dem es eingelernt wurde.

**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-object-finder-de/1.1.0/troubleshooting.html#ts-status-codes) an.
2. Prüfen Sie, ob `input/object-id` auf `system/objects` steht.
3. Lesen Sie die vier Werte unter `input/crop/`. Erwartet: alle `0` (das ganze Bild) oder eine Region, die das Teil enthält.
4. Setzen Sie `input/confidence-threshold` auf `0.4`, führen Sie die Suche mit echten Teilen aus und notieren Sie den `score` der echten Treffer in `output/result`. Erwartet: Der verwendete Schwellwert liegt unter dem schlechtesten Score eines echten Teils.
5. Vergleichen Sie ein Bild, in dem das Teil verfehlt wird, mit dem Bild, aus dem das Objekt eingelernt wurde. Erwartet: dieselbe Orientierung und derselbe Arbeitsabstand.

**Lösung**

- **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 Scores knapp unter dem Schwellwert liegen:** Setzen Sie `input/confidence-threshold` etwas unter den schlechtesten Score, den ein echtes Teil erzeugt. Liegen die Scores nahe am Schwellwert oder sind die Bilder verrauscht, setzen Sie `input/preprocess/blur-sigma-x` auf `1.0` (die Glättung ist standardmäßig aus) und messen Sie erneut.
- **Wenn das Teil in bestimmten Orientierungen verfehlt wird:** Lernen Sie ein weiteres Objekt in der verfehlten Orientierung ein, zum Beispiel `screw-m6-tilted`, und suchen Sie es in einem eigenen Durchlauf. Keine Einstellung behebt das.
- **Wenn das Teil in einem anderen Arbeitsabstand verfehlt wird:** Lernen Sie ein Objekt in diesem Abstand ein.
- **Wenn das Teil nicht im Bild war:** Das Ergebnis ist korrekt; es muss nichts geändert werden.

Siehe [Ein Objekt finden](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/finding-an-object.html) und [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `input/object-id`, dem Schwellwert, den gemessenen Scores und der `.png`-Datei des Objekts.

### Problem: Ein Teil wird mehrfach gemeldet {#faq-duplicate-matches}

**Symptome**

`matches` in `output/result` enthält für ein Teil eine Häufung von Treffern, die wenige Pixel auseinanderliegen.

**Mögliche Ursachen**

- `input/nms-min-dist` ist `0` (der Standardwert), was jeden Treffer behält.
- `input/nms-min-dist` ist kleiner als der Abstand zwischen den Treffern eines Teils.

**Diagnose**

1. Lesen Sie `input/nms-min-dist` des Moduls. `0` behält jeden Treffer.
2. Vergleichen Sie `x` und `y` der Treffer eines Teils mit der Größe des Teils in Pixeln.

**Lösung**

- Setzen Sie `input/nms-min-dist` auf etwa die halbe Größe des Teils in Pixeln, zum Beispiel `40`. Fallen mehrere Treffer in diesen Abstand, wird nur der mit dem höchsten Score behalten.

Der Standardwert `0` ist nur sinnvoll, wenn Teile tatsächlich dichter beieinanderliegen als ihre eigene Größe. Siehe [Die Suche abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `output/result` und dem Wert von `input/nms-min-dist`.

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

**Symptome**

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

**Mögliche Ursachen**

- Der nächste Durchlauf hat begonnen. Jeder Durchlauf leert seine eigenen Ausgaben, sobald er beginnt, bevor irgendetwas fehlschlagen kann. Ein Durchlauf, der aus irgendeinem Grund fehlschlägt, hinterlässt sie leer.
- Ein mit `-1` (busy) abgelehnter Aufruf leert 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-object-finder-de/1.1.0/lumiscan-object-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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Abfolge der Aufrufe Ihres Programms.

## Objekte {#ts-objects}

### Problem: Eine hochgeladene `.png`-Datei erscheint nicht auf `system/objects` {#faq-object-not-listed}

**Symptome**

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

**Mögliche Ursachen**

- Die Liste wurde nicht aktualisiert. `system/objects` wird nur beim Start, beim Verzeichniswechsel durch `system/set-object-dir` und beim Speichern einer Vorlage durch `system/create-object` aktualisiert. Auf anderem Weg hinzugefügte Dateien - ein Upload oder eine SSH-Sitzung auf ctrlX OS, eine auf einem PC von Hand hineinkopierte Datei - werden beim nächsten dieser Ereignisse übernommen.
- Der Dateiname endet nicht auf ein kleingeschriebenes `.png`. `.PNG`-Dateien werden übersprungen.
- Die Datei liegt in einem Unterverzeichnis. Nur Dateien auf der obersten Ebene des Objektverzeichnisses werden aufgeführt.
- Die Datei liegt in einem anderen Verzeichnis als dem, das `system/object-dir` nennt.

**Diagnose**

1. Lesen Sie `system/object-dir`. Erwartet: Es nennt das Verzeichnis, das die Datei enthält.
2. Prüfen Sie den Dateinamen. Erwartet: Er endet auf ein kleingeschriebenes `.png`, und die Datei liegt auf der obersten Ebene des Verzeichnisses.

**Lösung**

- **Wenn Dateiname oder Ablageort falsch sind:** Verwenden Sie einen kleingeschriebenen `.png`-Dateinamen auf der obersten Ebene des Objektverzeichnisses.
- **Danach:** Führen Sie `system/set-object-dir` aus oder starten Sie die Anwendung neu. Erwartet: `system/objects` führt das Objekt auf.

Siehe [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-storage.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `system/object-dir`, `system/objects` 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-object` 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 Anwendungsprotokoll.
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: object-id is empty - name the object to search for, see system/objects
   ```

**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-object`.

Siehe [Objekte auf einem Bild-Stream finden (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-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 verschwunden {#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 wirken sofort, werden aber erst gespeichert, wenn Sie es verlangen; 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.

**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-object-finder-de/1.1.0/troubleshooting.html#general-checks)). Erwartet: `lumiscan-object-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 Anwendungsprotokoll des Starts. 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, ob 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 zurückkommt, speichern Sie auch die Modulliste. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/module-management.html) und [In der Einstellungsdatei erhalten](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-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-object-finder-de/1.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `lumiscan-object-finder.json` und den Moduldateien `<module-id>.json`.

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

**Symptome**

Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start. Ihre Knoten unter `hdvisionsystems/lumiscan-object-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-object-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 Object Finder, `SWL-W-XCx-OBJECTxFDxHDVS-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-object-finder-de/1.1.0/lumiscan-object-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-object-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-object-finder-de/1.1.0/lumiscan-object-finder/module-management.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-object-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 Object 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 Anwendungsprotokoll zum Zeitpunkt des Fehlers - auf ctrlX OS aus dem ctrlX Logbook oder mit `journalctl`, auf einem PC die Konsolenausgabe der Anwendung.
- **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-object-finder.json`, die `<module-id>.json` des betroffenen Moduls 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-object-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.

# Release Notes: v1.1.0 – LumiScan Object Finder

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

Erstes funktionsfähiges Release von LumiScan Object Finder. Frühere Versionen registrierten die Data-Layer-Knoten der Anwendung, lieferten aber ein festes Platzhalterergebnis zurück, sodass nichts von dem Folgenden vorher nutzbar war.

## Neu

**Formbasierte Objekterkennung.** `<module>/find-object/execute` durchsucht ein Kamerabild nach einem bekannten Objekt und meldet jedes Vorkommen, jeweils mit Position, Größe der übereinstimmenden Vorlage, Score und Namen des Objekts. Das Matching erfolgt auf Gradientenorientierungen statt auf Pixelintensitäten und toleriert daher Beleuchtungsänderungen und Oberflächentexturen, an denen Intensitätskorrelation scheitert.

**Ein Objekt ist ein Bild**, gespeichert als `<object-dir>/<object-id>.png`, wobei der Dateiname die Objekt-ID ist. Der Detektor dreht oder skaliert es nicht, sodass ein Teil, das in mehreren Orientierungen erkannt werden muss, mehrere Objekte ist - `screw-m6-front`, `screw-m6-tilted` -, nach denen nacheinander gesucht wird. Siehe [Objektspeicher](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/object-storage.html).

**Ein Objekt pro Suche.** `<module>/find-object/input/object-id` nennt das Objekt und ist **erforderlich**; ein leerer Wert wird mit Statuscode `-2` abgelehnt. Es gibt keinen Durchlauf „nach allem suchen": Ein Detektor wird um ein Bild herum aufgebaut; die Suche nach mehreren Objekten bedeutete also mehrere Detektoren, und der Detektor verarbeitet jedes Mal das ganze Bild einmal - der teure Teil. Die Methode einmal pro Objekt auszuführen, hält diese Kosten sichtbar.

**Einlernen von der Live-Kamera.** `system/create-object/execute` schneidet eine Region aus einem Kamerabild aus und speichert sie als `<object-id>.png`, sodass ein Objekt in der echten Beleuchtung im echten Arbeitsabstand eingelernt werden kann, ohne Dateien zu übertragen. Das Speichern unter einer bestehenden ID ersetzt diese, und `output/object-path` meldet, wo die Datei abgelegt wurde.

**Mehrere Module**, jedes mit eigenem `find-object`, eigenen Einstellungen und Ergebnissen, sodass eine Installation mehrere Kameras gleichzeitig überwachen kann. Eine Lizenz gilt für zehn Module.

**Ein Objektverzeichnis für die Anwendung**, `system/object-dir`, dessen Objekte auf `system/objects` aufgelistet werden - ein Eintrag pro `.png`, was zugleich die vollständige Liste der Vorlagen ist. `system/set-object-dir` wechselt es und speichert die Wahl.

**Eine Geschwindigkeitseinstellung, die wirkt.** `input/preprocess/bin-size` sucht mit geringerer Auflösung: Sowohl das Bild als auch das Bild des Objekts werden vor dem Matching um diesen ganzzahligen Faktor verkleinert, sodass die Kosten mit der Pixelzahl sinken. Auf einem Full-HD-Bild mit einem 128x128-Objekt war `2` gemessen etwa sechsmal schneller bei unverändertem Score und `4` etwa vierzehnmal schneller. Das erkauft es mit Präzision - Positionen werden auf `bin-size` Pixel quantisiert - und mit Detail, denn ein weit genug gebinntes Objekt verliert die Kanten, auf die sich der Detektor stützt, und wird abgelehnt, was als fehlgeschlagener Durchlauf und nicht als fehlendes Teil gemeldet wird. Positionen werden immer in den Pixeln des Bildes gemeldet, das Sie konfiguriert haben. `input/pyramid` klingt wie eine Geschwindigkeitseinstellung und ist keine: Tiefere Pyramiden waren gemessen etwas **langsamer**.

**Eine Region of Interest pro Durchlauf**, `input/crop`, und die Wahl, ob Positionen in Bild- oder Ausschnittskoordinaten gemeldet werden.

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

## Wissenswert

Die zu durchsuchende Region wird genau wie konfiguriert durchsucht - der Detektor braucht eine bestimmte Größe und füllt bis dahin auf, statt einen Teil Ihrer Region wegzulassen. Positionen bleiben exakt, sodass ein bei y=300 gemeldeter Treffer bei y=300 im von Ihnen konfigurierten Bild liegt.

Ein leeres Ergebnis bedeutet, dass das Objekt nicht im Bild war, und nichts anderes. Jeder andere Grund, aus dem eine Suche leer zurückkommen könnte - das Bild des Objekts fehlt, das Bild ist unbrauchbar, eine Pyramidenebene ist ungültig, das Bild hat zu wenig Kontrast, als dass der Detektor sich darauf stützen könnte, `bin-size` hat zu wenig davon übrig gelassen -, wird vor dem Start der Suche abgefangen und als negativer Statuscode gemeldet. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/lumiscan-object-finder/execution-status.html).

Ungültige Eingaben werden alle gemeinsam gemeldet, jede mit Nennung der fehlerhaften Eingabe und ihres Werts.

Objekte und das Objektverzeichnis werden immer relativ zum Konfigurationsverzeichnis der Anwendung interpretiert. Absolute Pfade und Pfade, die daraus hinausführen, werden abgelehnt.

# LumiScan Object Finder

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

|   |   |   |
| --- | --- | --- |
| ![Eine Schraube, zweimal eingelernt: screw-m6 und screw-m6-tilted](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/_images/intro/step-1.svg)<br><br>**Das Objekt einlernen.** Aus dem Kamerabild, ein Objekt je Ausrichtung. | ![Drei Schrauben gefunden und umrandet](https://docs.hdvisionsystems.com/de/lumiscan-object-finder-de/1.1.0/_images/intro/step-2.svg)<br><br>**Am Umriss wiederfinden.** Der Abgleich der Kontur macht es robust gegen Licht und Oberfläche. | Beispielergebnis<br><br><br><br><br><br><br>Treffer<br>3<br><br><br>Position<br>820, 400 px<br><br><br>Score<br>0.93<br><br><br>Objekt<br>screw-m6<br><br>**Das Ergebnis an die SPS geben.** Position, Größe, Score und Objektname jedes Treffers. |

LumiScan Object Finder findet bekannte Objekte im Kamerabild an ihrer Form, den Kanten ihres Umrisses. Dadurch ist er robust gegen wechselndes Licht und unterschiedliche Oberflächen. Sie lernen ein Objekt aus dem Kamerabild ein; die App meldet dann jeden Treffer mit Position, Größe, Score und Objektname. Einsatz: Anwesenheits- und Zählprüfung, Robotergriff, Sortieren gemischter Teile auf dem Band und Lageprüfung, auf ctrlX OS oder einem Windows- oder Ubuntu-PC.

LumiScan Object 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; wo sie sich unterscheiden, wird darauf hingewiesen.

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