# LumiScan AI Object Matching 2.1.0.9 – complete documentation

> All pages of the LumiScan AI Object Matching 2.1.0.9 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-ai-object-matching-de/2.1.0/

# Beschreibung – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/description.html

LumiScan AI Object Matching erkennt mit neuronalen Netzen trainierte Objekte in Bildern und meldet deren Position und Orientierung in Pixelkoordinaten.

Die Anwendung läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC) oder auf einem PC (Windows 11 oder Ubuntu 24.04) und wird über den Data Layer gesteuert: den ctrlX Data Layer auf ctrlX OS, LumiScan Keryx auf einem PC. Konfiguriert wird sie über Konfigurationsdateien der Anwendung und der Modelle. Auf ctrlX OS wird sie aus dem App Store installiert.

Was für jede LumiScan-App gleich ist - wie Adressen aufgebaut sind, die Aufrufmuster Handshake, Execute und Stream, Statuscodes, Einstellungen und Werkzeuge -, ist im Handbuch [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html) beschrieben. Dieses Handbuch behandelt nur, was für LumiScan AI Object Matching spezifisch ist; seine Seiten beschreiben die eigenen Knoten der App.

Anders als regelbasierte Bildverarbeitung stützt sich AI Object Matching auf ein trainiertes neuronales Netz. Das Modell und seine zugehörige Beschreibungsdatei werden mit dem LumiScan Training Framework erstellt und gemeinsam in die Anwendung hochgeladen.

## Woher die Bilder kommen

Die Anwendung nimmt Bilder nicht direkt von einer Kamera auf. Sie liest Bilddaten, die eine andere Anwendung über den Data Layer veröffentlicht.

Zum Beispiel kann der LumiScan Cam Driver die Bilder liefern:

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

Die konfigurierte Bildquelle muss die Bilddaten und die erforderlichen Bildinformationen im erwarteten Format bereitstellen.

## Modelle

Ein trainiertes Modell legt fest, welche Objekte die Anwendung erkennen kann. Modelle werden mit dem LumiScan Annotation Framework und dem LumiScan Training Framework erstellt.

Jedes Modell besteht aus der Datei des neuronalen Netzes und der zugehörigen Beschreibungsdatei. Diese Dateien gehören zusammen und sollten immer als eine Einheit hochgeladen und behandelt werden.

Die Modellkonfiguration legt Parameter wie den Pfad des neuronalen Netzes, die Schwellwerte der Erkennung und den Inferenz-Provider fest. Siehe [Datei Model.json](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html#model-json-file).

## Module

Ein **Modul** ist eine konfigurierte Instanz von AI Object Matching. Es legt die Bildquelle, die zu verwendende Modellkonfiguration und den Ort fest, an dem die zugehörigen Ergebnisse und Steuerknoten im Data Layer verfügbar sind.

Jedes Modul vereint also:

- eine Bildquelle als Eingabe
- ein trainiertes Modell eines neuronalen Netzes
- Einstellungen der Erkennung
- Steuerknoten und Ergebnisse im Data Layer

Derzeit kann nur ein Modul zur Zeit aktiv sein.

# Voraussetzungen – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html

Um LumiScan auszuführen, werden die folgenden Komponenten benötigt:

**Auf ctrlX OS:**

- ctrlX CORE oder ctrlX IPC mit dem ctrlX Data Layer

**Auf einem PC:**

- PC mit Windows 11 oder Ubuntu 24.04 und LumiScan Keryx
- NVIDIA-GPU mit dem CUDA Toolkit 12.9 und cuDNN 9.11.1 für CUDA 12.9 (der Windows-Installer benötigt beides)

**Auf beiden:**

- Modelle neuronaler Netze, erstellt mit der Software LumiScan Training Framework

## Lizenz {#licence}

Wie LumiScan AI Object Matching 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-OBJxMATCHxHDVSx-V2NN`, eine Lizenz pro App-Instanz.<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 AI Object Matching 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.

## Optional: TPU-Beschleunigung (ctrlX OS)

Die TPU-Beschleunigung kann die Inferenzleistung des neuronalen Netzes verbessern, ist für den Betrieb von LumiScan aber nicht erforderlich.

Ist die TPU-Beschleunigung aktiviert, stellen Sie sicher, dass die ctrlX CORE eine TPU enthält und die folgenden Voraussetzungen an Software- und Hardware-Unterstützung erfüllt:

**Tabelle 1. Voraussetzungen für die TPU-Beschleunigung**

| ctrlX CORE Hardware | Mindestversion der App | Version der Hardware-Unterstützung der App |
| --- | --- | --- |
| X3 | \>= v1.2 | == 2.6.2 |
| X7 | \>= v1.1 | == 2.6.2 |

## Optional: GPU-Beschleunigung (PC)

Auf einem PC kann die Inferenz mit einer NVIDIA-GPU beschleunigt werden: Setzen Sie in der Modellbeschreibungsdatei `provider` auf `CUDA`, siehe [Datei Model.json](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html#model-json-file).

# Anleitung: AI Object Matching auf Kamerabildern ausführen (ctrlX CORE mit Hailo) – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/how-tos/run-ai-object-matching-on-a-camera-image.html

Diese Anleitung richtet LumiScan AI Object Matching auf einer ctrlX CORE so ein, dass es Objekte in den Bildern von LumiScan Cam Driver erkennt - mit einem in LumiScan Training trainierten Netz, beschleunigt durch die Hailo-TPU der ctrlX CORE.

Am Ende gilt:

- Das trainierte Netz ist auf der ctrlX CORE geladen und läuft auf der Hailo-TPU.
- Das Modul liest das Kamerabild direkt von LumiScan Cam Driver.
- Ein Schreibzugriff auf `inference/execute` erkennt die Objekte im aktuellen Bild.
- Die Detektionen - Position, Klasse, Score und, je nach Netz, Orientierung - liegen auf dem Data Layer.

## Bevor Sie beginnen {#prerequisites}

**Hardware**

- ctrlX CORE X3 oder X7 mit Hailo-TPU
- Eine an LumiScan Cam Driver angeschlossene Kamera
- Engineering-PC mit Browser und WinSCP

**Software**

- LumiScan AI Object Matching mit Lizenz, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html)
- LumiScan Cam Driver, konfiguriert, verbunden und aufnahmebereit
- Für die Hailo-TPU: die ctrlX-App **Hardware Support** in Version 2.6.2
- Optional: LumiScan Cockpit, um Bilder und Ergebnisse anzusehen

**Daten**

- Das trainierte Netz aus LumiScan Training: die Modelldatei (`.onnx`) und ihre Beschreibungsdatei (`.json`)

## Wie es zusammenhängt {#overview}

Die Einstellungen von LumiScan AI Object Matching sind Dateien in seinem Ordner `lumiscan-ai-object-matching`:

- `ai-object-matching.json` - die Anwendungskonfiguration. Ihre Liste `modules` nennt die zu ladende Moduldatei. Derzeit wird ein Modul unterstützt.
- Eine Moduldatei, zum Beispiel `ai-object-matching-module.json` - Name des Moduls, sein Netz und seine Bildquelle.
- Der Ordner `models` - das Netz: die Modelldatei und ihre Beschreibungsdatei `model.json` mit den Klassennamen, den Schwellwerten und dem Inferenz-Provider.

Der `name` des Moduls ist seine Adresse auf dem Data Layer: `hdvisionsystems/lumiscan-ai-object-matching/<name>/…`. Mit `externalImagePath` liest das Modul das Bild direkt aus einer anderen Anwendung, hier LumiScan Cam Driver. Jede Inferenz verwendet das Bild so, wie es in diesem Moment ist.

Die Dateien werden beim Start der Anwendung gelesen. Starten Sie sie nach jeder Änderung neu.

## Schritt 1 - Die Voraussetzungen für Hailo prüfen {#step-1-hailo}

1. Öffnen Sie in der ctrlX-Weboberfläche **Settings > Apps**.
2. Prüfen Sie, dass die App **Hardware Support** in Version 2.6.2 installiert ist.
3. Vergleichen Sie die Versionen mit der Tabelle **Voraussetzungen für die TPU-Beschleunigung** in [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html).

Die TPU ist optional. Ohne sie läuft das Netz auf der CPU (`provider` `CPU` in Schritt 4), nur langsamer.

## Schritt 2 - Das Netz hochladen {#step-2-upload}

Die Modelldateien werden per WebDAV hochgeladen.

1. Starten Sie WinSCP und legen Sie eine Verbindung an:
   - **File protocol**: `WebDAV`
   - **Encryption**: `TLS/SSL`
   - **Host name**: die Adresse der ctrlX CORE, mit Ihrem ctrlX-Benutzernamen und Passwort
2. Verbinden Sie sich und gehen Sie zu `/solutions/webdav/appdata/lumiscan-ai-object-matching/models`.
3. Kopieren Sie die Modelldatei (`.onnx`) und ihre Beschreibungsdatei (`.json`) in diesen Ordner.

Die Schritte im Einzelnen, mit Bildschirmfotos, stehen in [Daten per WebDAV hochladen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html#upload-using-webdav).

## Schritt 3 - Anwendung und Modul konfigurieren {#step-3-module}

1. Gehen Sie in der ctrlX-Weboberfläche zu **Home > Manage app data**, klicken Sie auf **Open file view** und öffnen Sie `lumiscan-ai-object-matching`.

2. Öffnen Sie `ai-object-matching.json` und prüfen Sie, dass die Liste `modules` Ihre Moduldatei nennt:
   ```json
   "modules": [
     "ai-object-matching-module.json"
   ]
   ```

3. Öffnen Sie die Moduldatei und setzen Sie:
   ```json
   {
     "name": "example",
     "neuralNetworkConfig": "models/model.json",
     "externalImagePath": "hdvisionsystems/lumiscan-cam-driver/camera1/output/image"
   }
   ```
   - `name` - der Name des Moduls auf dem Data Layer. Nur Kleinbuchstaben, Ziffern, `-` und `_`.

   - `neuralNetworkConfig` - der Pfad der hochgeladenen Beschreibungsdatei, relativ zum Anwendungsordner.

   - `externalImagePath` - der Bildknoten des Kameramoduls, hier `camera1` von LumiScan Cam Driver. Der Knoten muss `data`, `width`, `height` und `pixel-type` bereitstellen.

     Behalten Sie die Einträge `$schema` und `meta` der Datei bei. Alle Parameter sind in [Modulkonfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html) beschrieben.

## Schritt 4 - Die Hailo-TPU in der Modellbeschreibung wählen {#step-4-model}

Öffnen Sie `models/model.json`. Ihre Parameter erzeugt LumiScan Training; ändern Sie nur diese:

```json
{
  "pathToNetwork": "model.onnx",
  "provider": "HAILO",
  "deviceIndex": 0
}
```

- `pathToNetwork` - die Modelldatei, relativ zu `model.json`.
- `provider` - `HAILO` für die TPU, `CPU` ohne sie.
- `deviceIndex` - derzeit immer `0`.

In derselben Datei legt `thresholdList` je Klasse den Mindest-Score von `0.0` bis `1.0` fest, den eine Detektion braucht. Siehe [Die Datei model.json](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html#model-json-file).

## Schritt 5 - Neu starten und das Modul prüfen {#step-5-restart}

1. Speichern Sie alle geänderten Dateien.
2. Wählen Sie unter **Settings > Apps** **LumiScan AI Object Matching** aus und klicken Sie auf **Restart**.
3. Öffnen Sie **Settings > Data Layer** und gehen Sie zu `hdvisionsystems/lumiscan-ai-object-matching`.

Erwartet: ein Ordner mit dem `name` des Moduls, hier `example`, und `example/control/inference/ready` ist `true`, sobald das Netz geladen ist.

Fehlt das Modul oder bleibt `ready` auf `false`, lesen Sie `example/control/status/text` und das Anwendungsprotokoll. Häufige Ursachen sind ein falscher Pfad in der Moduldatei oder in `model.json`, ein `name` mit Großbuchstaben und eine fehlende Lizenz. Siehe [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html).

## Schritt 6 - Die Inferenz ausführen {#step-6-inference}

1. Nehmen Sie mit LumiScan Cam Driver ein Bild auf, zum Beispiel mit einem Schreibzugriff auf `hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute`.
2. Schreiben Sie auf `hdvisionsystems/lumiscan-ai-object-matching/example/control/inference/execute`. Der Schreibzugriff kehrt zurück, wenn die Inferenz beendet ist.
3. Lesen Sie `example/control/status/code`.

Erwartet: Der Statuscode ist `0`, und `example/output/package-identifier` ist um eins gestiegen.

- `100001` bedeutet: Es gab kein Bild zu lesen. Nehmen Sie ein Bild auf und führen Sie die Inferenz erneut aus.
- `-1` bedeutet: Die Inferenz ist fehlgeschlagen. Das Modul nimmt dann nur noch einen Reset an: schreiben Sie auf `example/control/reset/execute` und prüfen Sie das Protokoll.

> [!NOTE]
> Ein Client wartet nur wenige Sekunden darauf, dass ein `execute`-Aufruf zurückkehrt. Dauert die Inferenz auf einem großen Bild länger, starten Sie sie stattdessen mit dem ready/request-Handshake auf `example/control/inference`. Der Handshake endet immer beim Statuscode `3`; den Erfolg erkennen Sie an `output/package-identifier`, das nur nach einer erfolgreichen Inferenz steigt. Siehe [Die Inferenz initialisieren](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html).

## Schritt 7 - Die Detektionen lesen {#step-7-result}

Die Detektionen liegen auf

```
hdvisionsystems/lumiscan-ai-object-matching/example/output/result
```

Für jedes erkannte Objekt enthält das Ergebnis Position, Klasse und Score und, wenn das Netz dafür trainiert wurde, die Orientierung. Wie Sie das Ergebnis in einem SPS-Programm lesen, steht in [Ergebnisdaten mit FlatBuffers lesen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html).

Um die Detektionen visuell zu prüfen:

- In LumiScan Cockpit zeigt ein Modul, das auf dem Bildstream der Kamera inferiert, die Rahmen auf den Live-Bildern. Siehe [Inferenz auf einem Bildstream (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html).
- Für eine einzelne Inferenz speichert `example/control/save-result-image/execute` das Ergebnisbild zur Fehlersuche.

## Ergebnis {#result}

- Das trainierte Netz läuft auf der Hailo-TPU der ctrlX CORE.
- Das Modul liest das Kamerabild von LumiScan Cam Driver direkt.
- Ein Schreibzugriff auf `inference/execute` erkennt die Objekte im aktuellen Bild.
- Die Detektionen liegen auf `output/result`, bereit für die SPS oder den Roboter.

In der Produktion ist ein Zyklus: mit LumiScan Cam Driver aufnehmen, auf `inference/execute` schreiben, den Statuscode prüfen, `output/result` lesen.

# Allgemeines Konzept des Handshakes – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html

Die Kommunikation mit der Anwendung LumiScan AI Object Matching beruht auf dem allgemeinen Konzept des Handshakes. Die Namenskonvention für Handshake-Parameter besteht in der Regel aus der **Funktion** und den Namen **-ready** oder **-request**.

Der Handshake funktioniert auf dem ctrlX Data Layer und auf LumiScan Keryx gleich. Seine allgemeinen Regeln sind in [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) beschrieben; diese Seite beschreibt, wie AI Object Matching ihm folgt und wo es abweicht.

**Tabelle 1. Allgemeines Konzept des Handshakes: Adresse**

| Adresse | Beschreibung |
| --- | --- |
| `<parent address>/<functionality name>/ready` | Schreibgeschützt, von unserer App gesetzt, um anzuzeigen, ob die jeweilige Funktion ausgeführt werden darf. |
| `<parent address>/<functionality name>/request` | Beschreibbar. Wird vom Anwender gesetzt, um unsere Anwendung zur Ausführung der jeweiligen Funktion zu veranlassen. |

## Ausführung einer Funktion

> [!NOTE]
> Um nicht jedes Mal die gesamte Adresse zu wiederholen, werden in diesem Abschnitt der **unveränderliche Teil** mit der übergeordneten Adresse und der **variable Funktionsname** (inference, reset) durch **XXX** ersetzt.
>
> Die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready` wird also als **XXX/ready** geschrieben.
>
> Entsprechend wird die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request` als **XXX/request** geschrieben.

Um eine Funktion auszuführen, führen Sie die folgenden Schritte aus (siehe auch die Abbildung [Schritte der Funktionsausführung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#functionality-execution-steps)):

1. Warten Sie, bis XXX/ready auf **True** gesetzt ist.
2. Setzen Sie XXX/request auf **True**.
   > [!NOTE]
   > Stellen Sie sicher, dass jeweils nur ein Prozess auf XXX/request zugreift.
   >
   > Das Ergebnis der Ausführung ist **undefiniert**, wenn:
   >
   > a. Prozess A XXX/request auf True setzt.
   >
   > b. Prozess B XXX/request auf False setzt, ohne Prozess A zu berücksichtigen.
   >
   > c. Unsere Anwendung könnte dadurch das XXX/request von Prozess A übersehen.
3. Warten Sie, bis XXX/ready auf **False** wechselt: Die Anwendung hat den Request erkannt.
4. Setzen Sie XXX/request auf **False**.
5. Warten Sie, bis XXX/ready wieder **True** ist: Die Funktion ist abgeschlossen.
6. Lesen Sie `control/status/code` und die Ergebnisse.

**Schritte der Funktionsausführung**

```mermaid
%% Der ready/request-Handshake. Mermaid rendert es im Browser; bearbeiten und Vorschau unter https://mermaid.live
sequenceDiagram
  autonumber
  participant C as Client (SPS oder Programm)
  participant M as Modul
  M-->>C: ready = true: die Funktion kann starten
  C->>M: request = true
  M-->>C: ready = false: die Anforderung wurde gesehen
  C->>M: request = false
  Note over M: führt die Funktion aus
  M-->>C: ready = true: die Funktion ist fertig
  C->>M: control/status/code und output/ lesen
```

## Wann eine Funktion läuft {#when-a-functionality-runs}

Nicht jede Funktion wartet, bis XXX/request zurückfällt, bevor sie startet:

**Tabelle 2. Wann die einzelnen Funktionen laufen**

| Funktion | Läuft | `status/code` am Ende |
| --- | --- | --- |
| `inference` | Sofort, sobald die Anwendung den Request erkennt. `status/code` ist `2` (running), solange sie läuft, danach `3` (waitingForClient), solange die Anwendung darauf wartet, dass XXX/request zurückfällt. | **`3`, unabhängig davon, ob die Inferenz erfolgreich war.** Siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference). |
| `reset` | Sofort, ohne zu warten, bis XXX/request zurückfällt. Läuft in jedem Zyklus erneut, solange XXX/request **True** bleibt. | `0` |
| `list-result-files`, `load`, `save`, `save-result-image`, `remove` | Nachdem XXX/request zurückgefallen ist. `status/code` ist vom Request bis zum Abschluss `2`. | `0` oder ein Fehler (unter `0`) |

Solange das Modul einen Fehler hat, ignoriert es jeden Request außer `reset`. XXX/ready zeigt weiterhin **True**, aber der Request wird nie quittiert: XXX/ready fällt nicht. Fordern Sie `reset` an.

Solange der Bild-Stream läuft, ist `inference/ready` **False**. Eine trotzdem angeforderte Inferenz setzt `status/code` auf `100002` (StreamActive) und wird nicht quittiert.

## Ausgang einer Inferenz {#outcome-of-an-inference}

Eine über den Handshake angeforderte Inferenz endet unabhängig von ihrem Ausgang mit `status/code` `3`. Den Ausgang erkennen Sie an `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/package-identifier`: Er steigt mit jeder erfolgreichen Inferenz um eins, und nur dann.

Ist er nicht gestiegen, ist die Inferenz fehlgeschlagen. Entweder:

- konnte das Bild nicht gelesen werden: Es gab kein Bild, oder es war leer. Stellen Sie ein Bild bereit und fordern Sie die Inferenz erneut an; oder
- die Inferenz selbst ist fehlgeschlagen. Das Modul hat dann einen Fehler und ignoriert jeden Request außer `reset` (siehe oben). Fordern Sie `reset` an und prüfen Sie das Log der Anwendung auf die Ursache.

Um den Ausgang direkt zu lesen, starten Sie die Inferenz stattdessen mit `control/inference/execute`. `status/code` behält ihn dann: `0`, `100001` oder `-1`. Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#execute-a-method).

# Inferenz starten – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html

Diese Seite listet die Steuerknoten eines Moduls auf und beschreibt, wie Sie eine Inferenz ausführen. Die Knoten des Bild-Streams sind in [Inferenz auf einem Bild-Stream](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html) aufgeführt, die `system`-Knoten in [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html).

## Data Layer {#data-layer}

LumiScan AI Object Matching bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-ai-object-matching` an.

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

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan AI Object Matching bietet:

- [ready/request-Handshakes](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html)
- [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html)
- einen [Stream](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html), der seine Ergebnisse veröffentlicht (experimentell)
- 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.

## Adressen

**Tabelle 1. Adressen der Funktionen**

| Funktion | Zugriff | Adresse |
| --- | --- | --- |
| Inferenz | Schreibgeschützt | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready` |
| Inferenz | Beschreibbar | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request` |
| Inferenz | Nur schreiben (Methode) | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/execute` |
| Reset | Schreibgeschützt | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/ready` |
| Reset | Beschreibbar | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/request` |
| Reset | Nur schreiben (Methode) | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/reset/execute` |
| Status | Schreibgeschützt | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/code` |
| Status | Schreibgeschützt | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/text` |
| Ergebniszähler | Schreibgeschützt | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/package-identifier` |

`output/package-identifier` steigt mit jeder erfolgreichen Inferenz um eins, und nur dann.

## Schritte zur Inferenz mit einem externen Bild

> [!NOTE]
> Um nicht jedes Mal die gesamte Adresse zu wiederholen, wird in diesem Abschnitt der **unveränderliche Teil** mit der übergeordneten Adresse durch **XXX** ersetzt.
>
> Die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready` wird also als **XXX/inference/ready** geschrieben.
>
> Entsprechend wird die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request` als **XXX/inference/request** geschrieben.

Die Anwendung liest das Bild von der externen Adresse, die für das Netz konfiguriert ist, so, wie es beim Start der Inferenz vorliegt. Sie prüft nicht, ob das Bild neu ist: Ein Bild, das sich seit der letzten Inferenz nicht geändert hat, wird erneut inferiert.

So starten Sie die Inferenz:

1. Prüfen Sie XXX/inference/ready = True.[^1]

> [!NOTE]
> Die Anwendung lädt die Konfigurationen automatisch und richtet die neuronalen Netze ein. XXX/inference/ready ist **False**, solange sie eingerichtet werden, solange der Bild-Stream läuft, ohne Lizenz und nachdem die Einstellungen auf dem Data Layer geändert wurden (`status/code` `-5`, Neustart erforderlich). Prüfen Sie XXX/status/code und das Log für weitere Informationen.

2. Merken Sie sich den Wert von `output/package-identifier`.
3. Setzen Sie XXX/inference/request := True
4. Warten Sie, bis XXX/inference/ready = False. Die Inferenz läuft bereits.

> [!NOTE]
> Falls die Anwendung nicht erkannt hat, dass sich die Variable geändert hat:
>
> a. Stellen Sie sicher, dass jeweils nur ein Prozess auf XXX/inference/request zugreift.
>
> b. Ist die letzte Inferenz fehlgeschlagen, ignoriert das Modul jeden Request außer reset. Fordern Sie einen Reset an.
>
> c. Wenden Sie sich an hdvisionsystems.

5. Setzen Sie XXX/inference/request := False
6. Warten Sie, bis XXX/inference/ready = True.
7. Prüfen Sie, ob `output/package-identifier` um eins gestiegen ist.\
   `status/code` ist jetzt `3`, unabhängig davon, ob die Inferenz erfolgreich war: siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference).\
   Sie können das Ergebnis jetzt unter `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result` prüfen.

## Schritte zur Inferenz mit einem Eingabebild

> [!NOTE]
> Um nicht jedes Mal die gesamte Adresse zu wiederholen, wird in diesem Abschnitt der **unveränderliche Teil** mit der übergeordneten Adresse durch **XXX** ersetzt.
>
> Die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready` wird also als **XXX/inference/ready** geschrieben.
>
> Entsprechend wird die Adresse `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request` als **XXX/inference/request** geschrieben.

So setzen Sie das Eingabebild:

1. Suchen Sie im Data Layer die folgende Adresse[^2]: `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image`
2. Kopieren Sie das Rohbild auf die folgende Adresse: `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image`
3. Setzen Sie die zugehörige Bildbreite, Bildhöhe und das PixelFormat unter dem Pfad `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image`

> [!NOTE]
> Bei einem RGB-Bild ist das Datenlayout Höhe, Breite, Kanal. Mit anderen Worten: Die RGB-Werte eines Pixels liegen in den Rohdaten direkt nebeneinander.

So starten Sie die Inferenz:

1. Prüfen Sie XXX/inference/ready = True.[^1]

> [!NOTE]
> Die Anwendung lädt die Konfigurationen automatisch und richtet die neuronalen Netze ein. Solange XXX/inference/ready **True** ist, können Sie eine Inferenz ausführen.

2. Merken Sie sich den Wert von `output/package-identifier`.
3. Setzen Sie XXX/inference/request := True
4. Warten Sie, bis XXX/inference/ready = False. Die Inferenz läuft bereits.

> [!NOTE]
> Falls die Anwendung nicht erkannt hat, dass sich die Variable geändert hat:
>
> a. Stellen Sie sicher, dass jeweils nur ein Prozess auf XXX/inference/request zugreift.
>
> b. Ist die letzte Inferenz fehlgeschlagen, ignoriert das Modul jeden Request außer reset. Fordern Sie einen Reset an.
>
> c. Wenden Sie sich an hdvisionsystems.

5. Setzen Sie XXX/inference/request := False
6. Warten Sie, bis XXX/inference/ready = True.
7. Prüfen Sie, ob `output/package-identifier` um eins gestiegen ist.\
   `status/code` ist jetzt `3`, unabhängig davon, ob die Inferenz erfolgreich war: siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference).\
   Sie können das Ergebnis jetzt unter `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result` prüfen.

## Eine Methode ausführen {#execute-a-method}

Jede Funktion kann statt über den Handshake auch mit einem einzelnen Schreibvorgang auf ihren `execute`-Knoten gestartet werden:

`hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/<function>/execute`

für `inference`, `reset`, `list-result-files`, `load`, `save`, `save-result-image` und `remove`. Der Schreibvorgang kehrt zurück, wenn die Funktion abgeschlossen ist. Sie führt denselben Code aus wie der Handshake, und ihre Ergebnisse erscheinen auf denselben Ausgabeknoten.

Zwei Ergebnisse sind auseinanderzuhalten:

- **Ob die Funktion überhaupt gestartet werden konnte**, meldet der Schreibvorgang selbst. Ein abgelehnter Schreibvorgang wird nie in eine Warteschlange gestellt. Die Ergebnisse heißen auf den beiden Data Layern unterschiedlich; ihre Bedeutung ist dieselbe (siehe auch [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results)):

  | ctrlX Data Layer | LumiScan Keryx | Bedeutung | Was zu tun ist |
  | --- | --- | --- | --- |
  | `DL_OK` | `Ok` | Die Funktion wurde ausgeführt. | Lesen Sie `control/status/code` für ihren Ausgang. |
  | `DL_TOO_MANY_OPERATIONS` | `TooManyOperations` | Eine andere Funktion des Moduls läuft, über den Handshake oder ein anderes `execute`. | Wiederholen Sie den Aufruf. |
  | `DL_INVALID_OPERATION_MODE` | `InvalidOperationMode` | Das `ready` der Funktion ist **False**, zum Beispiel `inference`, solange der Bild-Stream läuft. | Bringen Sie das Modul zuerst in den passenden Zustand; bloßes Wiederholen schlägt weiter fehl. |
  | `DL_RESOURCE_UNAVAILABLE` | `ResourceUnavailable` | Die Anwendung wird beendet; oder die Einstellungen wurden auf dem Data Layer geändert und ein Neustart ist erforderlich (`status/code` `-5`); oder das Modul hat nach einer fehlgeschlagenen Inferenz einen Fehler. `reset/execute` wird wegen des Fehlers nie abgelehnt. | Nach einem Fehler führen Sie `reset` aus. Nach einer Änderung der Einstellungen starten Sie die Anwendung neu, siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#restart-required). |

- **Ob die Funktion erfolgreich war**, wird auf `control/status/code` und `control/status/text` gemeldet. Anders als beim Handshake lässt `execute` den Ausgang dort stehen: Nach `inference/execute` ist er `0`, `100001` oder `-1`.

Halten Sie jeden Aufruf kurz: Ein Client gibt das Warten nach wenigen Sekunden auf (auf LumiScan Keryx standardmäßig nach 2 s, siehe [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html#timeouts)). Eine Inferenz auf einem großen Bild oder einem langsamen Gerät kann länger dauern; verwenden Sie dann den Handshake.

## Statuscode-Werte {#status-code-values}

Die Werte `0` bis `3` und `-1` bis `-5` sind die Modulstatuscodes, die allen LumiScan-Anwendungen gemeinsam sind, siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#module-status). `100001` und `100002` sind spezifisch für AI Object Matching.

**Tabelle 2. Beschreibung der Statuscode-Werte**

| Statuscode-Nummer | Text | Bedeutung |
| --- | --- | --- |
| 0 | "ready" | Die letzte Funktion wurde erfolgreich ausgeführt, die Anwendung ist bereit, die nächste Funktion auszuführen. |
| 1 | "settingUp" | Das Modul oder die Funktion wird noch eingerichtet. |
| 2 | "running" | Die Funktion läuft gerade. |
| 3 | "waitingForClient" | Wartet auf den Client (in der Regel darauf, dass XXX/request zurückfällt). Außerdem das Ende jeder über den Handshake angeforderten Inferenz, unabhängig davon, ob sie erfolgreich war: siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference). |
| 100001 | "ImageQueueEmpty" | Das Bild konnte nicht gelesen werden: Der Bildknoten (`input/image` oder die externe Bildadresse) enthält keine Daten oder konnte nicht gelesen werden. Kein Fehler: Stellen Sie ein Bild bereit und führen Sie die Inferenz erneut aus. |
| 100002 | "StreamActive" | Eine Inferenz wurde angefordert, während der Bild-Stream läuft. Sie wird abgelehnt, kein Fehler. Siehe [Inferenz auf einem Bild-Stream](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html). |
| -1 | "undefinedError" | Etwas ist schiefgegangen, und wir haben dafür keinen eigenen Fehlercode angelegt. |
| -2 | "invalidSetting" | Die angegebene Einstellungsdatei konnte nicht geladen werden. |
| -3 | "invalidInput" | Eines der Eingabefelder war ungültig. |
| -4 | "MissingLicense" | Stellen Sie sicher, dass die richtige Lizenz installiert ist. |
| -5 | "restartRequired" | Die Einstellungsdateien wurden auf dem Data Layer geändert: Starten Sie die Anwendung neu. Siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#restart-required). |

[^1]: Die Bedeutung aller Statuscode-Werte ist in der Tabelle [Statuscode-Werte](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values) am Ende dieses Kapitels erklärt.
[^2]: Ist die Anwendung für die Verwendung eines Eingabebilds konfiguriert, sollte die angegebene Adresse vorhanden sein.

# Zugriff auf Ergebnisdaten mit FlatBuffers – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html

Diese Seite gilt für ctrlX OS (ctrlX CORE oder ctrlX IPC): Sie beschreibt, wie ein ctrlX-SPS-Programm das Ergebnis liest.

LumiScan AI Object Matching veröffentlicht das Ergebnis jeder Inferenz auf dem ctrlX Data Layer als binäre FlatBuffers-Nachricht. Ein SPS-Programm kann diese Nachricht nur mit dem Schema interpretieren, das ihren Aufbau beschreibt. Die Anwendung stellt deshalb die Schemadatei `object_detection.fbs` bereit.

Dieses Kapitel beschreibt, wie Sie das Schema beziehen, wie Sie es in ctrlX PLC Engineering importieren und wie Sie das Ergebnis lesen, einschließlich Position und Score eines erkannten Objekts.

## Ergebnisknoten

**Tabelle 1. Eigenschaften des Ergebnisknotens**

| Eigenschaft | Wert |
| --- | --- |
| Knotenadresse | `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result` |
| Zugriff | Schreibgeschützt |
| Datentyp | FlatBuffers |
| Adresse des registrierten Typs | `types/hdvisionsystems/lumiscan-ai-object-matching/object_detection` |
| Schemadatei | `object_detection.fbs` |
| Schema-Namespace | `hdv.object_detection2d` |
| Root-Typ | `Result` |

Der Knoten enthält das Ergebnis der letzten Inferenz. Lesen Sie ihn erst, nachdem die Inferenz abgeschlossen und erfolgreich war: Beim Handshake ist `output/package-identifier` um eins gestiegen (`status/code` ist am Ende jeder über den Handshake angeforderten Inferenz `3`); bei `control/inference/execute` ist `status/code` `0`. Siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference) und [Statuscode-Werte](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values).

## Voraussetzungen

- ctrlX PLC Engineering 2.6 oder neuer.
- Die Bibliotheken `CXA_Datalayer` und `CXA_Flatbuffers` sind im **Library Manager** des SPS-Projekts referenziert. `CXA_Datalayer` liest Knoten vom Data Layer. `CXA_Flatbuffers` stellt die Basis-Funktionsbausteine der FlatBuffers-Funktionsbausteine bereit, die der Import erzeugt. Prüfen Sie nach dem Import den Library Manager. Fehlt eine Bibliothek, fügen Sie sie dort hinzu (siehe auch [Die ctrlX-Data-Layer-Bibliothek installieren](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-install-datalayer-library)).
- LumiScan AI Object Matching ist installiert und wurde mindestens einmal mit einer gültigen Lizenz gestartet (siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html)).

## Schritt 1: Schemadatei beziehen

Die Anwendung kopiert das Schema bei jedem Start in ihren Anwendungsdatenordner auf der ctrlX CORE. So laden Sie es herunter:

1. Melden Sie sich an der Weboberfläche von ctrlX OS an und öffnen Sie **Manage app data** (siehe [Ordnerstruktur von LumiScan AI Object Matching](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/folder-structure.html)).
2. Öffnen Sie den Ordner `lumiscan-ai-object-matching/schemas/flatbuffers`.
3. Klicken Sie in der Spalte **Actions** von `object_detection.fbs` auf das Download-Symbol und speichern Sie die Datei auf dem Engineering-PC.

Alternativ laden Sie die Datei über WebDAV herunter (siehe [Daten hochladen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html)).

> [!NOTE]
> Der Ordner `schemas` wird beim Start der Anwendung angelegt, nach der Lizenzprüfung. Existiert der Ordner nicht, ist die Anwendung nicht erfolgreich gestartet. Prüfen Sie, ob eine gültige Lizenz installiert ist, und lesen Sie das Systemprotokoll. Siehe [Der Ordner schemas existiert nicht](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-schemas-folder-missing).
>
> Die Anwendung löscht den Ordner `schemas` bei jedem Start und legt ihn neu an. Bearbeiten Sie keine Dateien in diesem Ordner; Änderungen gehen verloren. Das Schema passt immer zur installierten Version der Anwendung.

## Schritt 2: Schema in das SPS-Projekt importieren

1. Öffnen Sie in ctrlX PLC Engineering das SPS-Projekt.
2. Klicken Sie im Gerätebaum mit der rechten Maustaste auf **Application**.
3. Wählen Sie **Import from FlatBuffers file…**.
4. Wählen Sie die heruntergeladene Datei `object_detection.fbs`.

![Gerätebaum von ctrlX PLC Engineering mit dem geöffneten Kontextmenü von Application auf Import from FlatBuffers file](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/plc-import-flatbuffers.png)

*Abbildung 1. Import from FlatBuffers file*

PLC Engineering fügt der Anwendung die folgenden Funktionsbausteine hinzu. Ihre Namen bestehen aus dem Schema-Namespace und dem Typnamen.

**Tabelle 2. Vom Import erzeugte Funktionsbausteine**

| Funktionsbaustein | Zweck |
| --- | --- |
| `hdv_object_detection2d_Result` | Wurzel der Nachricht. Liefert den besten Score und die beste Klasse sowie den Zugriff auf das Array der Instanzen. |
| `hdv_object_detection2d_Instance` | Ein erkanntes Objekt: Klassenindex, Score und Bounding Box. |
| `hdv_object_detection2d_OrientedBoundingBox` | Mittelpunkt, Größe und Winkel der Bounding Box einer Instanz. |
| `hdv_object_detection2d_InstanceTVec` | Zum Lesen der Ergebnisse nicht erforderlich (siehe [Bekannte Meldung: Identifier 'VectorT' not defined](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-known-message-vectort)). |

### Bekannte Meldung: Identifier 'VectorT' not defined {#lumiscan-known-message-vectort}

Je nach Version von ctrlX PLC Engineering zeigt der Editor des Funktionsbausteins `hdv_object_detection2d_InstanceTVec` die Meldung `Identifier 'VectorT' not defined`. Die Meldung beeinträchtigt das Lesen der Ergebnisse nicht. Ursachen und Schritte sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html) beschrieben:

- [Nach dem Import erscheint die Meldung "Identifier 'VectorT' not defined"](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-vectort-not-defined)

### Die ctrlX-Data-Layer-Bibliothek installieren {#lumiscan-install-datalayer-library}

Ist **Import from FlatBuffers file…** im Kontextmenü nicht verfügbar, fehlt die ctrlX-Data-Layer-Bibliothek. Installieren Sie sie wie folgt und wiederholen Sie dann Schritt 2:

1. Wählen Sie in der Menüleiste von PLC Engineering **Tools** > **Library Repository…**.

![Menü Tools von ctrlX PLC Engineering mit hervorgehobenem Befehl Library Repository](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/plc-install-datalayer-1.png)

*Abbildung 2. Befehl Library Repository*

2. Suchen Sie nach `CXA_Datalayer`, wählen Sie die Bibliothek aus und klicken Sie auf **Open**.

![Dialog Find Library mit dem Suchbegriff CXA_Datalayer und der ausgewählten Bibliothek CXA_Datalayer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/plc-install-datalayer-2.png)

*Abbildung 3. Suche nach der Bibliothek CXA_Datalayer*

## Schritt 3: Ergebnis im SPS-Programm lesen

1. Führen Sie eine Inferenz mit dem Handshake aus, der in [Inferenz starten](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html) beschrieben ist.
2. Warten Sie, bis die Inferenz abgeschlossen ist, und prüfen Sie, ob sie erfolgreich war: `inference/ready` ist wieder **True** und `output/package-identifier` ist um eins gestiegen. Bei `control/inference/execute` prüfen Sie stattdessen, ob `status/code` 0 ist.
3. Lesen Sie den Knoten `hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result` mit dem Funktionsbaustein `DL_ReadNodeValue` der Bibliothek `CXA_Datalayer`. Der Funktionsbaustein liefert den Wert in einem `DL_NodeValue`.
4. Übergeben Sie Adresse und Größe des Puffers (`GetData` und `GetSize` des `DL_NodeValue`) an `getRootAsResult` von `hdv_object_detection2d_Result`.
5. Lesen Sie die Felder des Ergebnisses mit den `get`-Methoden der erzeugten Funktionsbausteine.

> [!NOTE]
> Die erzeugten Funktionsbausteine lesen den empfangenen Puffer an Ort und Stelle; sie kopieren ihn nicht. Verwenden oder kopieren Sie die Werte, bevor der Knoten erneut gelesen wird.

## Beispiel: Position und Score einer Instanz lesen {#lumiscan-example-instance}

Das Array `instances` des Ergebnisses ist nach Score absteigend sortiert. Instanz 0 ist daher die Instanz mit dem höchsten Score. Das Beispiel liest die Position (x, y), den Score und den Klassenindex dieser Instanz.

Deklaration:

```text
PROGRAM PRG_ReadObjectMatchingResult
VAR
    // Data Layer access (CXA_Datalayer)
    fbReadResult : DL_ReadNodeValue;
    nvResult     : DL_NodeValue;    // receives the FlatBuffers buffer
    bRead        : BOOL;            // set to TRUE to read the node once
    sNode        : STRING(255) := 'hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/result';

    // FlatBuffers readers, generated by "Import from FlatBuffers file..."
    fbResult     : hdv_object_detection2d_Result;
    fbInstance   : hdv_object_detection2d_Instance;
    pBox         : POINTER TO hdv_object_detection2d_OrientedBoundingBox;

    // Values of the instance with the highest score
    bFound       : BOOL;
    rX           : REAL;            // x of the bounding box center [pixel]
    rY           : REAL;            // y of the bounding box center [pixel]
    rScore       : REAL;            // score [0.0 - 1.0]
    uClassIndex  : ULINT;           // index into class-names
END_VAR
```

Implementierung:

```text
// 1. Read the node. A rising edge on bRead starts one read.
fbReadResult(Execute := bRead, NodeName := sNode, NodeValue := nvResult);

IF fbReadResult.Done THEN
    bFound := FALSE;

    IF nvResult.GetSize() > 0 THEN
        // 2. Point the generated reader at the received buffer.
        fbResult.getRootAsResult(data := nvResult.GetData(), size := nvResult.GetSize());

        // 3. The instances are sorted by score, so instance 0 has the highest score.
        IF fbResult.getInstancesLength() > 0 THEN
            IF fbResult.getInstances(j := 0, result := ADR(fbInstance)) THEN
                rScore      := fbInstance.GetScore();
                uClassIndex := fbInstance.GetClassIndex();

                // 4. The position is part of the bounding box.
                pBox := fbInstance.getOrientedBoundingBox();
                IF pBox <> 0 THEN
                    rX     := pBox^.GetCenterX();
                    rY     := pBox^.GetCenterY();
                    bFound := TRUE;
                END_IF
            END_IF
        END_IF
    END_IF
END_IF

// 5. End the access.
IF fbReadResult.Done OR fbReadResult.Error THEN
    bRead := FALSE;
    fbReadResult(Execute := bRead, NodeName := sNode, NodeValue := nvResult);
END_IF
```

Ersetzen Sie `<network name>` in `sNode` durch den Namen des Netzes. Setzen Sie `bRead` erst auf TRUE, nachdem die Inferenz abgeschlossen und erfolgreich war (siehe Schritt 3). Ist `fbReadResult.Error` TRUE, werten Sie `fbReadResult.ErrorID` und `fbReadResult.ErrorIdent` aus.

**Tabelle 3. Im Beispiel verwendete Methoden**

| Wert | Methode | Typ | Einheit oder Bereich |
| --- | --- | --- | --- |
| Anzahl der Instanzen | `fbResult.getInstancesLength()` | `UDINT` |   |
| Instanz nach Index | `fbResult.getInstances(j, result)` | `BOOL` | `TRUE`, wenn die Instanz existiert |
| Score | `fbInstance.GetScore()` | `REAL` | 0.0 bis 1.0 |
| Klassenindex | `fbInstance.GetClassIndex()` | `ULINT` | Index in `class-names` |
| Bounding Box | `fbInstance.getOrientedBoundingBox()` | `POINTER TO hdv_object_detection2d_OrientedBoundingBox` |   |
| x des Mittelpunkts | `pBox^.GetCenterX()` | `REAL` | Pixel |
| y des Mittelpunkts | `pBox^.GetCenterY()` | `REAL` | Pixel |

> [!NOTE]
> Die Sortierung nach Score ist das Verhalten der aktuellen Version. Das Schema erlaubt, dass die Sortierreihenfolge in einer künftigen Version konfigurierbar wird. `getBestIndex()` von `hdv_object_detection2d_Result` liefert immer den Index der Instanz mit dem höchsten Score; er ist 0, solange die Instanzen nach Score sortiert sind. Verwenden Sie ihn statt des festen Index 0, wenn das Programm unabhängig von der Sortierreihenfolge bleiben soll.

### Alle Instanzen lesen

Um alle Instanzen auszuwerten, durchlaufen Sie das Array in einer Schleife. Da die Instanzen nach Score sortiert sind, kann die Schleife bei der ersten Instanz unter einem Mindest-Score abbrechen. Das folgende Fragment ersetzt Schritt 3 der Implementierung. Es benötigt die zusätzlichen Deklarationen `i : UDINT;` und `rMinScore : REAL := 0.5;`.

```text
i := 0;
WHILE i < fbResult.getInstancesLength() DO
    IF fbResult.getInstances(j := i, result := ADR(fbInstance)) THEN
        rScore := fbInstance.GetScore();

        IF rScore < rMinScore THEN
            EXIT;   // sorted by score: no instance with a higher score follows
        END_IF

        pBox := fbInstance.getOrientedBoundingBox();
        IF pBox <> 0 THEN
            rX := pBox^.GetCenterX();
            rY := pBox^.GetCenterY();
            // Use or store the values of instance i here.
        END_IF
    END_IF
    i := i + 1;
END_WHILE
```

Verwenden Sie keine `FOR`-Schleife mit der vorzeichenlosen Anzahl (`FOR i := 0 TO count - 1`): Ist die Anzahl 0, läuft die Obergrenze auf den größten `UDINT`-Wert über.

## Aufbau des Ergebnisses

Die folgenden Tabellen beschreiben den Inhalt von `object_detection.fbs`. Die Schemadatei ist die maßgebliche Definition.

**Tabelle 4. Result (table, Root-Typ)**

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `instances` | `[Instance]` | Erkannte Objekte, nach Score absteigend sortiert (höchster Score zuerst). Das Array kann Objekte verschiedener Klassen enthalten; das SPS-Programm muss die benötigte Klasse auswählen (siehe [Klassennamen und Klassenfilter](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-class-names-and-filters)). |
| `best_index` | `ulong` | Index der Instanz mit dem höchsten Score in `instances`. Immer 0, solange die Instanzen nach Score sortiert sind. |
| `best_score` | `float` | Score der besten Instanz, im Bereich 0.0 bis 1.0. |
| `best_class_index` | `ulong` | Klassenindex der besten Instanz. |
| `image_id` | `ulong` | Package Identifier des Eingabebilds, zu dem das Ergebnis gehört. In Versionen vor Oktober 2026 war es ein 16-Bit-`short`. |
| `image_name` | `string` | Nicht verwendet. |
| `requested_timestamp` | `ulong` | Zeitpunkt, zu dem die Anwendung den Inferenz-Request angenommen hat, den die SPS auf **True** gesetzt hatte. |
| `timestamp` | `ulong` | Zeitstempel des Eingabebilds. Typ und Auflösung hängen von der Zeitstempelquelle der Anwendung `lumiscan-cam-driver` ab, die das Bild geliefert hat. |
| `status` | `ulong` | Nicht verwendet. Prüfen Sie den Ausgang mit `status/code` (siehe [Statuscode-Werte](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values)). |

**Tabelle 5. Instance (struct)**

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `oriented_bounding_box` | `OrientedBoundingBox` | Position, Größe und Orientierung des erkannten Objekts im Bild. |
| `class_index` | `ulong` | Index der erkannten Klasse (siehe [Klassennamen und Klassenfilter](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-class-names-and-filters)). |
| `score` | `float` | Score der Erkennung, im Bereich 0.0 bis 1.0. |

**Tabelle 6. OrientedBoundingBox (struct)**

| Feld | Typ | Einheit | Beschreibung |
| --- | --- | --- | --- |
| `center_x` | `float` | Pixel | Horizontale Position des Box-Mittelpunkts. |
| `center_y` | `float` | Pixel | Vertikale Position des Box-Mittelpunkts. |
| `width` | `float` | Pixel | Breite der Box. |
| `height` | `float` | Pixel | Höhe der Box. |
| `angle` | `float` | Grad | Orientierung der Box. Die aktuelle Implementierung kann negative Winkel liefern; gehen Sie nicht davon aus, dass der Wert auf den Bereich 0.0 bis 360.0 normiert ist. |

## Klassennamen und Klassenfilter {#lumiscan-class-names-and-filters}

Mit der Standard-Klassenzuordnung bezeichnet `class_index` eine Klasse über ihre Position im Array der Klassennamen, das für das Netz konfiguriert ist. Verwenden Sie die folgenden Knoten, um Klassen aufzulösen und einzuschränken:

> [!NOTE]
> Ist eine eigene Neuzuordnung der Klassenindizes konfiguriert, folgt der veröffentlichte Klassenindex dieser Zuordnung und kann von der Position in `setting/class-names` abweichen. Interpretieren Sie das Ergebnis anhand der konfigurierten Zuordnung.

**Tabelle 7. Knoten zu den Klassen**

| Adresse | Zugriff | Beschreibung |
| --- | --- | --- |
| `hdvisionsystems/lumiscan-ai-object-matching/<network name>/setting/class-names` | Schreibgeschützt | Klassennamen des Netzes. Mit der Standardzuordnung ist die Position eines Namens im Array sein Klassenindex. |
| `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/class-filters` | Beschreibbar | Klassennamen, die in das Ergebnis aufgenommen werden. Lassen Sie das Array leer, um die Filterung zu deaktivieren. |

## Anwendung aktualisieren

Laden Sie nach einem Update der Anwendung das Schema erneut herunter und importieren Sie es erneut in das SPS-Projekt, damit das SPS-Programm das Schema der installierten Version verwendet.

# Inferenz auf einem Bild-Stream (experimentell) – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html

> [!IMPORTANT]
> Die Inferenz auf einem Bild-Stream ist **experimentell** (ab v2.2.0). Ihre Knoten können sich noch ändern. Verwenden Sie sie zur Evaluierung, und prüfen Sie sie mit Ihrem Netz und Ihrer Kamera, bevor Sie sich darauf verlassen.

Das allgemeine Konzept der Streams - Produzenten und Konsumenten, der Ergebnis-Envelope und seine Lineage - ist in [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) beschrieben. Diese Seite beschreibt den Stream von AI Object Matching. Er funktioniert auf dem ctrlX Data Layer und auf LumiScan Keryx gleich.

Auf Anfrage inferiert ein Modul ein Bild pro Request: Ihr Programm schreibt das Bild, oder der Cam Driver nimmt eines auf, und fordert dann die Inferenz an. Mit einem Bild-Stream veröffentlicht der Cam Driver jedes Bild, das er aufnimmt, auf `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 - seine Quelle -, inferiert die Bilder, sobald sie eintreffen, und veröffentlicht ein Ergebnis pro inferiertem Bild. Jedes Ergebnis trägt die Lineage seines Bildes - welche Kamera es aufgenommen hat, in welchem Lauf ihres 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-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#lineage).

Standardmäßig fällt das Modul nie hinter die Kamera zurück. Treffen Bilder schneller ein, als das Netz inferiert, inferiert es jeweils das neueste Bild, sobald die vorherige Inferenz abgeschlossen ist. Die Bilder dazwischen zählen als übersprungen. Wie viele Bilder warten dürfen, legt die Warteschlangengröße fest, siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#queue-size).

Ein Modul hat eine Quelle. Um die Bilder von zwei Kameras zu inferieren, verwenden Sie zwei Module.

Auf beiden Data Layern erreicht jedes Bild das Modul, in der richtigen Reihenfolge. Unterwegs verlorene Bilder werden in `statistics/lost-frames` gezählt: Jedes Bild trägt seine Nummer im Stream seiner Kamera.

## Einrichtung {#setting-up}

Jedes Modul hat die unten aufgeführten Stream-Knoten, ob es bereits eine Quelle hat oder nicht: Um sie zu verwenden, ist kein Neustart nötig. Entweder

- setzen Sie in der Konfigurationsdatei des Moduls den Abschnitt `stream`, zum Beispiel
  ```json
  "stream": {
      "enable": true,
      "address": "hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream"
  }
  ```

  Siehe [Konfigurationsdatei eines Moduls](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html). Eine geänderte Datei wirkt beim nächsten Start oder Reset; oder

- Sie schreiben zur Laufzeit die Eingaben von `control/subscribe` und rufen es auf, siehe [Abonnieren zur Laufzeit](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#subscribing).

Der Bild-Stream wird mit dem Netz, den Klassenfiltern und der Neuzuordnung des Moduls inferiert. Für ein anderes Netz oder andere Einstellungen verwenden Sie ein anderes Modul.

### In den Einstellungen gespeichert {#kept-in-the-settings}

Stream-Modus und Quelle sind Einstellungen des Moduls, im Abschnitt `stream` seiner Konfigurationsdatei. Ohne diesen Abschnitt, oder ohne `enable` darin, ist das Modul nicht im Stream-Modus. Der Stream-Modus benötigt eine Quelle: Eine Modulkonfigurationsdatei, in der `enable` auf `true` gesetzt ist und keine `address` steht, ist ungültig, und das Modul wird nicht geladen. Ebenso wenig ein Modul mit einem Schritt in `stream.onEntry`: Der Abschnitt enthält die Schritte des Streams jeder LumiScan-Anwendung, und AI Object Matching hat noch keine.

`control/subscribe/execute` und `control/unsubscribe/execute` speichern `enable`, `address`, `tag`, `queueSize` und `keepLatestOutput`, bevor sie sie anwenden. Nach einem Neustart abonniert das Modul dieselbe Quelle und startet, wenn `stream.enable` `true` ist, seinen Stream sofort - niemand muss die Methode erneut aufrufen. Das Speichern ändert nur diese Werte: Der Rest der Datei bleibt, wie er war, Kommentare eingeschlossen.

## Adressen {#addresses}

Alle Adressen unten beginnen mit `hdvisionsystems/lumiscan-ai-object-matching/<network name>/`. Der Stream folgt dem Aufbau einer Execute-Methode: `control/subscribe` besitzt seine Eingaben und Ausgaben.

**Tabelle 1. Methoden**

| Adresse | Bedeutung |
| --- | --- |
| `control/subscribe/execute` | Prüft alle `control/subscribe/input/…` gemeinsam, speichert sie in der Konfigurationsdatei des Moduls und wendet sie dann an: Der Stream folgt in seinem nächsten Zyklus, ohne Neustart. Siehe [Abonnieren zur Laufzeit](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die Quelle, die `control/unsubscribe/input/address` nennt, was auch den Stream-Modus beendet, und speichert das. Das Tag bleibt. |

**Tabelle 2. Eingaben**

| Adresse | Typ | Beim Start | Bedeutung |
| --- | --- | --- | --- |
| `control/subscribe/input/enable` | bool | `stream.enable`, oder `false` | `true` inferiert die Bilder der Quelle; `false` stoppt es. |
| `control/subscribe/input/address` | string | `stream.address`, oder leer | Der Stream-Ordner der Quelle, der das `frame` der Kamera enthält, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. |
| `control/subscribe/input/tag` | string | `stream.tag`, oder leer | Das Tag, das das Modul auf seine Ergebnisse setzt: Der Schritt des Moduls in der Lineage jedes Ergebnisses trägt es, sodass jeder, der ein Ergebnis weiter unten in der Kette liest, sieht, welches Modul es erzeugt hat. Leer: die Modul-ID, das letzte Segment der Adresse des Moduls - `example` für `hdvisionsystems/lumiscan-ai-object-matching/example`. Ein neues Tag markiert das nächste Ergebnis; die Quelle bleibt abonniert. |
| `control/subscribe/input/queue-size` | uint32 | `stream.queueSize`, oder 1 | Wie viele Bilder auf die Inferenz warten dürfen, 1 bis 64. Siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#queue-size). |
| `control/subscribe/input/keep-latest-output` | bool | `stream.keepLatestOutput`, oder `false` | `true` schreibt jedes Stream-Ergebnis zusätzlich in die normale Ausgabe. Siehe [Neuestes Ergebnis behalten](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#keep-latest-output). |
| `control/unsubscribe/input/address` | string | leer | Die Quelle, die `control/unsubscribe/execute` entfernt: die Adresse auf `setting/stream/address`. |

Das Schreiben einer Eingabe ändert für sich allein nichts: Erst `control/subscribe/execute` wendet die Eingaben an. Sie beginnen mit dem, was das Modul anwendet, und ein Reset setzt sie wieder auf die Werte der Datei, sodass ein Client eine Eingabe ändern und die Methode aufrufen kann.

Was die Quelle enthalten muss: Lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/meta/subscription-schema` (string, schreibgeschützt), für jedes Modul dasselbe. Es ist ein JSON Schema (draft-04) des `frame`-Knotens der Quelle, eines `stream_image` mit seiner `lineage` und seinem `image`, in seiner JSON-Form. Der Knoten ist experimentell.

**Tabelle 3. Ausgaben**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/output/stream/active` | bool | `true`, solange das Modul seinen Bild-Stream inferiert. |
| `control/subscribe/output/stream/result` | flatbuffer `stream_detections` | Das Ergebnis jedes inferierten Bildes, im selben Format wie `output/result`, und seine Lineage. Abonnieren Sie ihn, um jedes Ergebnis zu erhalten. Siehe [Das Ergebnis eines gestreamten Bildes](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#result). |
| `control/subscribe/output/stream/statistics/…` | uint64 | Zähler des laufenden oder letzten Streams, siehe [Die Statistik lesen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#statistics). |

**Tabelle 4. Einstellung**

| 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 das Modul gerade anwendet, wie im Abschnitt `stream` gespeichert. Ein Client findet hier die Bilder der Quelle: LumiScan Cockpit verwendet `setting/stream/address`, um die Ergebnisse auf den Livebildern einzuzeichnen. |
| `setting/settings-hash` | string | Der Hash der Einstellungen, mit denen die Ergebnisse erzeugt werden, als 16 Hexadezimalziffern. Siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#settings-hash). |

Solange `keep-latest-output` nicht gesetzt ist, werden die Ergebnisse des Streams nur auf `control/subscribe/output/stream/result` veröffentlicht, und `output/result`, `output/package-identifier`, `output/timestamp` und `output/image` behalten das Ergebnis der letzten Inferenz auf Anfrage.

## Das Ergebnis eines gestreamten Bildes {#result}

`control/subscribe/output/stream/result` enthält eine FlatBuffers-Tabelle vom Typ `stream_detections`, auf dem Data Layer registriert als `types/hdvisionsystems/lumiscan-ai-object-matching/stream_detections`. Ihr kompiliertes Schema wird als `bfbs/stream_detections.bfbs` installiert. Sie hat zwei Felder: `result`, dieselbe Tabelle wie `output/result` (`object_detection`), und `lineage`, siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#lineage).

Drei Felder von `result` beschreiben das Bild:

| Feld | Bedeutung |
| --- | --- |
| `image_id` | Die Nummer des Bildes seit dem Start des Streams: 1, 2, 3 und so weiter. Eine Lücke bedeutet, dass die Bilder dazwischen übersprungen wurden oder fehlgeschlagen sind. Eine 64-Bit-Zahl (`ulong`). In Versionen vor Oktober 2026 war es ein 16-Bit-`short`, das nach 32767 Bildern in negative Zahlen überlief. |
| `timestamp` | Wann das Bild eingetroffen ist, in Mikrosekunden seit der Epoche. |
| `requested_timestamp` | Wann die Inferenz auf dem Bild gestartet wurde, in Mikrosekunden seit der Epoche. Die Differenz zu `timestamp` ist die Zeit, die das Bild gewartet hat. |

Die Klassenfilter in `input/class-filters` und die Neuzuordnung der Klassenindizes des Moduls gelten wie bei der Inferenz auf Anfrage. Eine Klasse, die die Netzbeschreibung nicht benennt, wird mit ihrem Index veröffentlicht.

## Neuestes Ergebnis behalten {#keep-latest-output}

Mit gesetztem `keep-latest-output` wird jedes Stream-Ergebnis zusätzlich in die normale Ausgabe des Moduls geschrieben, so wie eine Inferenz auf Anfrage es schreibt: `output/result`, `output/timestamp` und `output/package-identifier`, weitergezählt ab den Inferenzen auf Anfrage. Ein Client, der die normale Ausgabe liest - zum Beispiel ein SPS-Programm, das für die Inferenz auf Anfrage geschrieben wurde -, sieht dort dann das neueste Stream-Ergebnis. Das Ausgabebild (`output/image`) wird nicht gezeichnet.

Es kostet eine Kopie jedes Ergebnisses und ist deshalb standardmäßig ausgeschaltet. Das Stream-Ergebnis auf `control/subscribe/output/stream/result` wird zuerst veröffentlicht.

## Die Lineage eines Ergebnisses {#lineage}

`lineage.steps` listet auf, woher das Ergebnis stammt, der 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 ihr Stream gestartet wurde, `sequence` die Nummer des Bildes in diesem Lauf, `external_id` die eigene Bildnummer der Kamera, `settings_hash` die Einstellungen der Kamera und `tag` das Tag des Cam Driver für die Kamera, standardmäßig ihre Modul-ID, zum Beispiel `camera1`.
2. Der Schritt des Moduls: `producer` ist die Adresse des Moduls, `hdvisionsystems/lumiscan-ai-object-matching/<network name>`; `run`, wann der Stream des Moduls gestartet wurde (jeder Start ist ein neuer Lauf); `sequence` die Nummer des Ergebnisses im Lauf; `settings_hash` die Einstellungen des Moduls, siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Bildes bis zur Veröffentlichung des Ergebnisses; `time_us`, wann es veröffentlicht wurde; `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`. Eine Quelle, die während des laufenden Streams geändert wird, behält den Lauf des Moduls: Die Ergebnisse der neuen Kamera werden weitergezählt, und der `producer` ihres ersten Schritts benennt sie. Zwei Ergebnisse desselben Kamerabildes, vor und nach einer Änderung der Einstellungen, unterscheiden sich im `settings_hash` des Modulschritts.

Ein Bild ohne Lineage - veröffentlicht von etwas anderem als dem Cam Driver - ergibt ein Ergebnis mit dem Schritt des Moduls allein. Ein Wert auf dem `frame`-Knoten des Streams, der kein `stream_image` ist, wird ignoriert und einmalig protokolliert.

## Der Einstellungs-Hash {#settings-hash}

`setting/settings-hash` und der `settings_hash` des Modulschritts in jedem Ergebnis bezeichnen, womit die Ergebnisse erzeugt werden. Der Hash ändert sich, wenn sich eines davon ändert:

- die Einstellungen der Modulkonfigurationsdatei, mit denen das Modul gestartet wurde - außer dem Abschnitt `stream` und `externalImagePath`, die die Bilder auswählen und nicht, was daraus gemacht wird;
- die Netzbeschreibung und die Netzdatei, die sie benennt, nach ihrem Inhalt - ein neues Netz unter dem alten Dateinamen ist ein neuer Hash; mit `simulateResult` stattdessen der Inhalt dieser Datei;
- `input/class-filters`;
- die Version der Anwendung.

Ein Reset liest die Netzbeschreibung und die Netzdatei erneut. Wenn ein Hash zum ersten Mal auftritt, schreibt das Modul die Einstellungen, für die er steht, nach `settings-history/<network name>-<hash>.json` im Konfigurationsordner der Anwendung, sodass ein in einem Ergebnis gefundener Hash später nachgeschlagen werden kann.

> [!NOTE]
> Ein Ergebnis trägt nur den Hash. Ein anderer Hash besagt, 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. Dasselbe gilt für den Hash der Kamera im Kameraschritt; was er abbildet, steht im Handbuch des Cam Driver, *Bilder streamen*.

## Abonnieren zur Laufzeit {#subscribing}

Eine SPS oder ein anderer Client ändert Quelle und Stream-Modus, während die Anwendung läuft, mit oder ohne laufenden Stream:

1. Schreiben Sie die Eingaben, die sich ändern, auf `control/subscribe/input/…` - für eine andere Kamera `control/subscribe/input/address`; für eine andere Markierung der Ergebnisse `control/subscribe/input/tag`; zum Starten oder Stoppen `control/subscribe/input/enable`.
2. Schreiben Sie `true` auf `control/subscribe/execute`.

Die Methode prüft alle Eingaben gemeinsam, speichert sie im Abschnitt `stream` und wendet sie dann an: `setting/stream/…` zeigt sie sofort, und ein laufender Stream folgt in seinem nächsten Zyklus. Eine andere Adresse ersetzt die Quelle - ein vorheriges Unsubscribe ist nicht nötig -, und die Bilder, die die alte Kamera noch wartend hatte, zählen als übersprungen. Tag, Warteschlangengröße und `keep-latest-output` wirken ohne erneutes Abonnieren: Ein neues Tag markiert das nächste Ergebnis.

Um die Quelle zu entfernen, schreiben Sie ihre Adresse auf `control/unsubscribe/input/address` und `true` auf `control/unsubscribe/execute`. Das beendet auch den Stream-Modus und speichert `enable` als `false` ohne Adresse. Das Tag bleibt: Es markiert die Ergebnisse des Moduls, nicht die Quelle. `control/subscribe/input/…` werden ebenfalls darauf gesetzt, sodass ein späteres `control/subscribe/execute`, das eine andere Eingabe ändert, die Quelle nicht zurückbringt. Ein `/` am Anfang oder Ende einer Adresse spielt keine Rolle.

Die Methoden antworten:

| ctrlX Data Layer | LumiScan Keryx | Wann |
| --- | --- | --- |
| `DL_OK` | `Ok` | Erledigt. |
| `DL_INVALID_VALUE` | `Rejected` | `control/subscribe`: `enable` ist `true` und die Adresse ist leer, oder die Warteschlangengröße liegt nicht zwischen 1 und 64. `control/unsubscribe`: Die Adresse ist nicht die Quelle, oder es gibt keine Quelle. Nichts hat sich geändert. |
| `DL_CREATION_FAILED` | `CreationFailed` | Die Konfigurationsdatei des Moduls konnte nicht geschrieben werden. Nichts hat sich geändert: Der Stream bleibt, wie er war. Die Antwort und das Log nennen den Grund. |
| `DL_RESOURCE_UNAVAILABLE` | `ResourceUnavailable` | Die Einstellungen wurden auf `system/settings` bearbeitet, und die Anwendung wartet auf einen Neustart. |

Ein Reset (`control/reset`) liest den Abschnitt `stream` der Modulkonfigurationsdatei erneut, wendet ihn an und setzt die Eingaben darauf: Ein laufender Stream folgt. Eine von Hand bearbeitete Datei wirkt also mit einem Reset.

Kann das Abonnement nicht eingerichtet werden, zum Beispiel weil die Kamera noch nicht läuft, versucht es das Modul alle 5 Sekunden erneut, solange der Stream läuft, und protokolliert den ersten Fehlschlag.

## Die Warteschlangengröße {#queue-size}

`control/subscribe/input/queue-size`, gespeichert als `stream.queueSize`, legt fest, wie viele Bilder auf die Inferenz warten dürfen: 1 bis 64, standardmäßig 1. Ein Bild, das eintrifft, wenn so viele warten, verdrängt das älteste davon, was in `statistics/skipped-frames` gezählt wird.

| Warteschlangengröße | Wirkung |
| --- | --- |
| 1 (Standard) | Das Modul inferiert das neueste Bild. Es fällt nie zurück; ist das Netz langsamer als die Kamera, überspringt es Bilder. |
| Mehr als 1 | Kurze Bildschübe werden vollständig inferiert, und weniger Bilder werden übersprungen. Ist das Netz länger langsamer als die Kamera, fällt das Modul zurück: Es inferiert Bilder, die bis zu so viele Inferenzen alt sind. Jedes wartende Bild hält ein ganzes Bild im Speicher. |

Eine geänderte Warteschlangengröße gilt für das nächste eintreffende Bild, ohne Neustart des Streams.

## Einen Stream ausführen {#running}

1. Stellen Sie sicher, dass der Stream des Cam Driver läuft: Sein `control/publish/output/stream/active` ist `true`.
2. Abonnieren Sie `control/subscribe/output/stream/result`.
3. Schreiben Sie `true` auf `control/subscribe/input/enable` - und die Adresse der Quelle, falls das Modul noch keine hat - und `true` auf `control/subscribe/execute`. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist. Ab dann treffen die Ergebnisse ein.
4. Zum Stoppen schreiben Sie `false` auf `control/subscribe/input/enable` und `true` auf `control/subscribe/execute`.

Beides wird gespeichert: Das Modul startet wieder so, wie es verlassen wurde. Der Stream kann vor dem Stream des Cam Driver gestartet werden; Ergebnisse treffen ein, sobald Bilder eintreffen.

## Inferenz auf Anfrage, während der Stream läuft {#while-streaming}

Beide verwenden dasselbe Netz, deshalb laufen sie nie gleichzeitig:

- `control/inference/ready` ist `false`, solange der Stream läuft.
- Ein Request auf `control/inference/request` wird mit Status `100002` (`StreamActive`) beantwortet. Er hinterlässt **keinen** Fehler, und kein Reset ist nötig.
- `control/inference/execute` antwortet mit `DL_INVALID_OPERATION_MODE` (LumiScan Keryx: `InvalidOperationMode`). Wiederholen Sie es nicht in einer Schleife: Stoppen Sie zuerst den Stream.
- Reset, list, load, save, save-result-image und remove funktionieren weiterhin. Ein Reset lädt das Netz neu, und der Stream läuft damit weiter.

## Gemessene Raten {#measured-rates}

Gemessen mit einer simulierten Kamera (1440 x 1080, Mono8), einem Detektionsnetz mit einer Eingabe von 640 x 480 auf einer NVIDIA GeForce RTX 2060 SUPER mit dem CUDA-Provider, unter Linux. Die Zahlen zeigen nur die Größenordnung.

- **ctrlX Data Layer:** Der Data Layer machte bei den Zahlen keinen Unterschied.
- **LumiScan Keryx auf einem PC (Windows):** Auf derselben GPU dauerte eine Inferenz etwa 53 ms, und 18,4 von 30 Bildern pro Sekunde wurden inferiert; die Tabelle zeigt den Lauf unter Linux.

| Kamera | Empfangen | Inferiert | Übersprungen | Inferenzzeit |
| --- | --- | --- | --- | --- |
| 10 Bilder/s | 10 /s | 10 /s | 0 | etwa 49 ms |
| 30 Bilder/s | 30 /s | 19,4 /s | 10,7 /s | etwa 51 ms |

Kein Bild ging verloren oder schlug fehl.

## Die Statistik lesen {#statistics}

Die Zähler stehen unter `control/subscribe/output/stream/statistics/`. Sie beginnen bei jedem Start des Streams bei null und werden, solange er läuft, etwa viermal pro Sekunde aktualisiert.

| 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. |
| `inferred-frames` | Inferierte Bilder, jedes mit einem auf `control/subscribe/output/stream/result` veröffentlichten Ergebnis. |
| `skipped-frames` | Nie inferierte Bilder: von neueren aus der Warteschlange verdrängt, während Inferenzen liefen (siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#queue-size)), oder wartend, als die Quelle ersetzt wurde. |
| `failed-frames` | Bilder, die nicht dekodiert oder inferiert werden konnten, zum Beispiel weil ihre Pixel nicht die Größe und das Pixelformat ausfüllen, die sie tragen. Das Log nennt den Grund. |
| `lost-frames` | Bilder, die verloren gingen, bevor sie eintrafen, ermittelt aus Lücken in der `sequence` der Kamera innerhalb eines Laufs ihres Streams. Ein neuer Lauf des Kamera-Streams oder eine neue Quelle beginnt die Zählung von vorn. |
| `inference-us` | Mikrosekunden, die alle Inferenzen gedauert haben. Teilen Sie durch `inferred-frames` für den Mittelwert. |

# Ordnerstruktur von LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/folder-structure.html

Die Einstellungen der Anwendung sind Dateien in ihrem Ordner `lumiscan-ai-object-matching`. Standardmäßig gibt es drei Dateien (Sie können später neue Dateien hinzufügen):

- **ai-object-matching.json** enthält die **Konfiguration der Anwendung**. Sie legt fest, wie viele Module mit neuronalen Netzen geladen werden.\
  Derzeit wird nur ein Modul unterstützt.
- **\<file name x>.json** (hier als Beispiel: **ai-object-matching-module.json**) Diese Datei enthält die **Konfiguration des Moduls**. Sie legt fest, wie das Netzmodul Bilddaten auswertet.
- **models** enthält zwei Unterdateien mit den Erkennungsparametern und dem Modell des neuronalen Netzes.

Die Einstellungen können auch auf dem Data Layer gelesen und geändert werden, siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html).

## Auf ctrlX OS: Bearbeiten mit der integrierten Website

1. Melden Sie sich an der Website von ctrlX OS an.
2. Gehen Sie zu **Home**.
3. Wählen Sie **Manage app data**.

![Startseite von ctrlX OS mit hervorgehobenem Manage app data](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/ctrlx-os-home-manage-app-data.png)

4. Klicken Sie auf die drei Punkte und wählen Sie **File View**.

![Ansicht Manage app data mit dem geöffneten Dateiaktionsmenü auf File View](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/manage-app-data-file-view-menu.png)

5. Gehen Sie zum Ordner der jeweiligen Anwendung.

![Ordnerliste des aktiven Ordners mit den Ordnern datalayer und lumiscan-ai-object-matching](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/manage-app-data-active-folder.png)

6. Der Ordner enthält die drei oben beschriebenen Dateien.

![Inhalt des Ordners lumiscan-ai-object-matching mit models](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/lumiscan-folder-contents.png)

7. Ein Linksklick auf den gewünschten Dateinamen öffnet den Inhalt der Datei automatisch im rechten Fenster.

![ai-object-matching.json geöffnet in der Dateiinhaltsansicht](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/json-file-content-view.png)

## Auf einem PC: Einstellungsordner

Auf einem PC ist der Einstellungsordner:

- (Windows) `%APP_RESOURCE_DIR%\etc\lumiscan-ai-object-matching`, wenn die Umgebungsvariable `APP_RESOURCE_DIR` gesetzt ist;
- (Windows) andernfalls `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-ai-obj-mat\etc\lumiscan-ai-object-matching`.

Öffnen Sie die Dateien in einem beliebigen Texteditor, vorzugsweise einem, der JSON gegen die Schemas im Ordner `schemas` prüft.

> [!NOTE]
> Ausführlichere Informationen zu jeder Datei finden Sie in den entsprechenden Abschnitten weiter hinten in diesem Handbuch.

# Konfigurationsdatei der Anwendung – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/application-configuration-file.html

Diese Anwendung kann mehrere Module zur Objekterkennung mit neuronalen Netzen ausführen. Jedes Modul benötigt eine zugehörige Konfiguration des Netzmoduls (.json).

Die allgemeinen Einstellungen der Anwendung LumiScan AI Object Matching stehen in der Datei **ai-object-matching.json**. Diese Datei legt fest, wie viele Module mit neuronalen Netzen geladen werden.

Ein Beispiel für die JSON-Einstellungen der Anwendungskonfiguration:

```json
{
    "meta": {
        "inputFileType": "LumiScan-CtrlX-AI-Object-Matching",
        "inputFileVersion": "1.0.0",
        "targetMachine": "MachineName",
        "programName": "AI-Object-Matching",
        "programVersion": "1.0.0"
    },
    "modules": [
        "ai-object-matching-module.json"
    ]
}
```

Die Beschreibung aller oben genannten Parameter finden Sie in der folgenden [Tabelle 1](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/application-configuration-file.html#table-1).

**Tabelle 1. Konfigurationsdatei der Anwendung: Beschreibung der JSON-Einstellungen**

| Parameter | Beschreibung |
| --- | --- |
| meta | Ort für Metainformationen: inputFileType und inputFileVersion sind erforderlich. |
| inputFileType | Muss in diesem Fall sein: `LumiScan-CtrlX-AI-Object-Matching` |
| inputFileVersion | Derzeit wird nur Version 1.0.0 unterstützt. |
| targetMachine | Optional. Tragen Sie hier den Namen der verwendeten Maschine ein, um anzuzeigen, dass die aktuelle Anwendungskonfiguration für genau diese Maschine verwendet wird. |
| programName | Optional. Dieser Parameter gibt an, von welcher Anwendung die aktuelle Datei verwendet wird. In diesem Fall: `AI-Object-Matching` |
| programVersion | Optional. Derzeit verwendete Programmversion. |
| modules | Enthält die erstellten Modellkonfigurationsdateien. |

> [!NOTE]
> Nach einer Änderung der Parameter sollte die Anwendung LumiScan AI Object Matching neu gestartet werden.

## Vollständige Referenz {#complete-reference}

Alle Einstellungen dieser Datei, wie sie ihr JSON-Schema `lumiscan-ai-object-matching.schema.json` festlegt, erzeugt für Version 2.1.0 (Beschreibungen aus dem Schema, auf Englisch):

| Einstellung | Typ | Standard | Zulässige Werte | Beschreibung |
| --- | --- | --- | --- | --- |
| `meta` | object |   |   | **Pflichtangabe.** Meta information about the application and current setting. This is mainly for information purpose and not used by the application itself |
| `meta/inputFileType` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/inputFileVersion` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/targetMachine` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/programName` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/programVersion` | string |   | nicht leer | **Pflichtangabe.** |
| `modules` | string[] |   | mindestens 1 Eintrag | **Pflichtangabe.** List of module setting files that will be loaded by the application |
| `system` | object |   |   |   |
| `system/debug` | boolean | `false` |   | Enable debug mode for the application. |
| `system/logLevel` | string | `INFO` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` | Log level for the application. |
| `system/storage` | object |   |   | Configuration for storage. The storage is used to store the images when save function is called. |
| `system/storage/type` | string |   | `Samba` | **Pflichtangabe.** The storage is a Samba storage. |
| `system/storage/parameters` | object |   |   | Parameters for the storage. The parameters are different for each storage type. |
| `system/storage/parameters/ip` | string |   | nicht leer | **Pflichtangabe.** The IP address of the Samba server. |
| `system/storage/parameters/remotePath` | string |   | nicht leer | **Pflichtangabe.** |
| `system/storage/parameters/domain` | string |   | nicht leer | **Pflichtangabe.** |
| `system/storage/parameters/username` | string |   | nicht leer | **Pflichtangabe.** |
| `system/storage/parameters/password` | string |   | nicht leer | **Pflichtangabe.** |

# Konfigurationsdatei eines Moduls – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html

Die Konfigurationseinstellungen des Moduls stehen in der Datei **\<file name x>.json** (in diesem Beispiel **ai-object-matching-module.json**) und legen fest, wie das Netzmodul Bilddaten auswertet.

Ein Beispiel für die JSON-Einstellungen der Modulkonfiguration:

```json
{
    "$schema": "schemas/lumiscan-ai-object-matching-module.schema.json",
    "meta":
    {
        "inputFileType": "LumiScan-CtrlX-AI-Object-Matching-Module",
        "inputFileVersion": "1.0.0",
        "targetMachine": "Example",
        "programName": "AI-Object-Matching",
        "programVersion": "1.0.0"
    },
    "name": "example",
    "neuralNetworkConfig": "models/model_description.json",
    "externalImagePath": "hdvisionsystems/lumiscan-cam-driver/camera1/output/image"
}
```

Die Beschreibung der oben genannten Parameter finden Sie in der folgenden [Tabelle 6](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html#table-6).

**Tabelle 1. Modulkonfiguration: Beschreibung der JSON-Einstellungen**

| Parameter | Beschreibung |
| --- | --- |
| meta | Ort für Metainformationen: inputFileType und inputFileVersion sind erforderlich. |
| inputFileType | Muss in diesem Fall sein: `LumiScan-CtrlX-AI-Object-Matching-Module` |
| inputFileVersion | Derzeit wird nur Version 1.0.0 unterstützt. |
| targetMachine | Optional. Tragen Sie hier den Namen der verwendeten Maschine ein, um anzuzeigen, dass die aktuelle Anwendungskonfiguration für genau diese Maschine verwendet wird. |
| programName | Optional. Dieser Parameter gibt an, von welcher Anwendung die aktuelle Datei verwendet wird. In diesem Fall: `AI-Object-Matching` |
| programVersion | Optional. Derzeit verwendete Programmversion. |
| name | Ein eindeutiger Bezeichner für das neuronale Netz, der auch als Netzname in der Data-Layer-Adresse verwendet wird: `hdvisionsystems/lumiscan-ai-object-matching/<name>/...`. Erlaubt sind nur Kleinbuchstaben, Ziffern, `-` und `_`. Ein Modul, dessen Name einen Großbuchstaben oder ein anderes Zeichen enthält, wird nicht geladen; das Log nennt den Namen, der stattdessen zu schreiben ist (`Network1` → `network1`). |
| neuralNetworkConfig | Der Dateipfad zu den Parametern des Modells des neuronalen Netzes. Diese Parameter werden vom LumiScan Training Framework erzeugt. |
| externalImagePath | Pfad zur Data-Layer-Adresse, die das Bild enthält. Die angegebene Bildadresse muss **data, height, width, pixel-type** enthalten.<br> <br> Ist er nicht angegeben, legt das Netzmodul einen zusätzlichen Pfad unter `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input` an, über den Anwender Rohbilder ohne eine weitere Anwendung in den Data Layer hochladen können. |
| stream | **Experimentell** (ab v2.2.0). Optional. Inferenz auf einem Bild-Stream aus einer Quelle: die Einstellungen unten. Ohne diesen Abschnitt, oder ohne `enable` darin, ist das Modul nicht im Stream-Modus. `control/subscribe/execute` und `control/unsubscribe/execute` speichern `enable`, `address`, `tag`, `queueSize` und `keepLatestOutput` hier, bevor sie sie anwenden; der Rest der Datei bleibt, wie er war, Kommentare eingeschlossen. Der Abschnitt hat in jeder LumiScan-Anwendung, die einen Stream abonniert, dieselben Schlüssel. Siehe [Inferenz auf einem Bild-Stream](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html). |
| stream.enable | `true`: Das Modul startet im Stream-Modus und inferiert die Bilder seiner Quelle von seinem Start an. Standardmäßig `false`. Benötigt `stream.address`: Ein Modul mit `enable` auf `true` und ohne Adresse wird nicht geladen. |
| stream.address | Der Bild-Stream, der inferiert wird: sein Ordner, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Das Modul abonniert den `frame`-Knoten des Ordners, dessen Bilder ihre Größe, ihr Pixelformat und ihre Lineage tragen; die Lineage jedes Ergebnisses benennt die Kamera. |
| stream.tag | Das Tag auf den Ergebnissen des Moduls: Der Schritt des Moduls in der Lineage jedes Stream-Ergebnisses trägt es, sodass jeder, der ein Ergebnis weiter unten in der Kette liest, sieht, welches Modul es erzeugt hat. Optional. Weggelassen oder leer: die Modul-ID, das letzte Segment der Adresse des Moduls - `example` für `hdvisionsystems/lumiscan-ai-object-matching/example`. |
| stream.queueSize | Wie viele Bilder auf die Inferenz warten dürfen: 1 bis 64, standardmäßig 1. 1 inferiert das neueste Bild; ein höherer Wert behält mehr Bilder, wenn das Netz zurückfällt. Siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#queue-size). |
| stream.keepLatestOutput | `true`: Jedes Stream-Ergebnis geht zusätzlich in die normale Ausgabe (`output/result`, der Zeitstempel und `output/package-identifier`). Standardmäßig `false`. Siehe [Neuestes Ergebnis behalten](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#keep-latest-output). |
| stream.onEntry | Die Schritte, die auf jedes eintreffende Bild vor der Inferenz angewendet werden, jeder ein Objekt mit einem `kind`. AI Object Matching hat noch keine: Lassen Sie den Eintrag weg oder leer (`[]`). Ein Schritt verhindert das Laden des Moduls, weil es ohne den Schritt inferieren würde, den seine Datei verlangt; das Log benennt ihn. |
| stream.onExit | Reserviert für Schritte, die auf jedes Ergebnis angewendet werden. Wird noch nicht gelesen: Die Anwendung protokolliert eine Warnung, und die Schritte werden nicht angewendet. |

> [!NOTE]
> Nach einer Änderung der Parameter sollte die Anwendung LumiScan AI Object Matching neu gestartet werden. Für den Abschnitt `stream` genügt ein Reset.
>
> Die Stream-Layouts früherer Test-Builds werden nicht mehr gelesen: `subscriptions` und `streamQueueSize` auf oberster Ebene sowie `stream.subscriptions` (eine Map mehrerer Quellen). Ein Modul hat jetzt eine Quelle: Verschieben Sie ihre Adresse nach `stream.address` und `streamQueueSize` nach `stream.queueSize`. Die Anwendung protokolliert eine Warnung, solange eine Moduldatei noch einen dieser Einträge enthält.

## Automatisches Kopieren eines externen Bildes

Um ein externes Bild automatisch aus einer anderen Anwendung zu kopieren, muss diese Anwendung eine Adresse mit den folgenden Parametern bereitstellen:

**Tabelle 2. Parameter des externen Bildes**

| Adresse | Typ |
| --- | --- |
| `<address>/data` | Array von uint8_t |
| `<address>/height` | uint32_t |
| `<address>/width` | uint32_t |
| `<address>/pixel-type` | string, mögliche Werte: Mono8, RGB8 |

**\<address>** ist das Bildfeld, das in der Modulkonfigurationsdatei unter `externalImagePath` angegeben ist.

> [!NOTE]
> Diese Schnittstelle ist für die Verwendung mit dem LumiScan Cam Driver entworfen und getestet. Die Kompatibilität mit Bilddaten anderer Anwendungen kann nicht garantiert werden.

## Vollständige Referenz {#complete-reference}

Alle Einstellungen dieser Datei, wie sie ihr JSON-Schema `lumiscan-ai-object-matching-module.schema.json` festlegt, erzeugt für Version 2.1.0 (Beschreibungen aus dem Schema, auf Englisch):

| Einstellung | Typ | Standard | Zulässige Werte | Beschreibung |
| --- | --- | --- | --- | --- |
| `meta` | object |   |   | **Pflichtangabe.** |
| `meta/inputFileType` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/inputFileVersion` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/targetMachine` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/programName` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/programVersion` | string |   | nicht leer | **Pflichtangabe.** |
| `name` | string |   | Muster `^[a-zA-Z0-9_-]+$` | **Pflichtangabe.** only [a-Z], [0-9], '-' and '\_' are allowed. Unique ID of the camera configuration. This is used to identify different camera on datalayer. |
| `neuralNetworkConfig` | string |   | nicht leer | **Pflichtangabe.** Path to network description file. |
| `externalImagePath` | string |   | nicht leer | If specified, the image will be loaded from the specified path instead of the ai-object-matching app managed input image. |
| `cropImage` | object |   |   | If specified, input image will be cropped and then used for inference. Note that the detected pixel position is related to original image. Use it if you want to accelerate the inference by reducing the image size. |
| `cropImage/startX` | number |   | ≥ 0 | **Pflichtangabe.** |
| `cropImage/startY` | number |   | ≥ 0 | **Pflichtangabe.** |
| `cropImage/width` | number |   |   | **Pflichtangabe.** |
| `cropImage/height` | number |   |   | **Pflichtangabe.** |
| `simulateResult` | string |   | nicht leer | If specified, the result will be simulated. This is useful for testing the application without the actual neural network. |
| `classIndexRemapping` | object |   |   | If specified, the detected object's index will be remapped to other index. Ke |
| `classIndexRemapping/<Name>` | integer |   |   |   |

## JSON-Schemas {#json-schemas}

Die Anwendung legt die JSON-Schemas ihrer Einstellungsdateien in ihrem Ordner `schemas` ab; diese Kopien passen immer zur installierten Version. Die Schemas von LumiScan AI Object Matching 2.1.0 stehen außerdem zum Download bereit: [JSON-Schemas von LumiScan AI Object Matching 2.1.0](https://docs.hdvisionsystems.com/schemas/lumiscan-ai-object-matching/2.1.0/index.html).

Damit ein Editor wie Visual Studio Code eine Kopie einer Einstellungsdatei prüft, die Sie auf Ihrem PC bearbeiten, lassen Sie deren Eintrag `$schema` auf das veröffentlichte Schema zeigen:

```json
{
  "$schema": "https://docs.hdvisionsystems.com/schemas/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching-module.schema.json",
  ...
}
```

Lassen Sie den Eintrag `$schema` der Dateien auf dem Gerät so, wie die Anwendung ihn geschrieben hat.

# Ordner models – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html

![Ordner models mit model.json und model.onnx](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/models-folder-contents.png)

Der Ordner models enthält zwei Dateien, die das LumiScan Training Framework erzeugt:

- **\<file name>.json** (zum Beispiel **model.json**) enthält die Erkennungsparameter und verweist auf das Modell des neuronalen Netzes.
- **\<file name>.onnx** (zum Beispiel **model.onnx**) enthält das trainierte Modell des neuronalen Netzes.

**Auf ctrlX OS:** Die Modelldateien müssen über WebDAV hochgeladen werden.[^1]

**Auf einem PC:** Kopieren Sie die Modelldateien in den Ordner `models` des Einstellungsordners, siehe [Daten hochladen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html#upload-on-a-pc).

## Datei Model.json {#model-json-file}

Die Datei `model.json` enthält die Parameter, die zur Konfiguration des für die Erkennung verwendeten Modells des neuronalen Netzes erforderlich sind.

Das folgende Beispiel zeigt die JSON-Struktur:

```json
{
    "classList": {
        "0": "nockeIO",
        "1": "nockeVerbogen"
    },
    "thresholdList": {
        "nockeIO": 0.02,
        "nockeVerbogen": 0.02
    },
    "resizedImageShape": {
        "height": 431,
        "width": 571
    },
    "normalizationMean": [
        123.67500305175781,
        116.27999877929688,
        103.52999877929688
    ],
    "normalizationStd": [
        58.39500045776367,
        57.119998931884766,
        57.375
    ],
    "spacialNMSRadius": 3,
    "pathToNetwork": "model.onnx",
    "provider": "CPU",
    "deviceIndex": 0
}
```

Alle Parameter werden vom LumiScan Training Framework erzeugt.

Nur `thresholdList`, `pathToNetwork`, `provider` und `deviceIndex` sollten von Hand geändert werden. Diese Parameter sind in [Tabelle 8](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html#table-8) beschrieben.

**Tabelle 1. Datei Model.json: Beschreibung der JSON-Einstellungen**

| Parameter | Beschreibung |
| --- | --- |
| `thresholdList` | Legt den Mindest-Schwellwert der Konfidenz für jede Erkennungsklasse fest.<br><br>- Die Werte müssen zwischen `0.0` und `1.0` liegen.<br>- Ein höherer Wert verlangt eine höhere Konfidenz der Erkennung.<br>- Der Wert `1.0` entspricht 100 % Konfidenz. |
| `pathToNetwork` | Gibt den Pfad zum trainierten Modell des neuronalen Netzes an, das für die Objekterkennung verwendet wird.<br><br>Der Pfad muss relativ zum Speicherort der aktuellen JSON-Datei sein. |
| `provider` | Gibt den Inferenz-Provider an. Mögliche Werte:<br><br>- Auf ctrlX OS: `CPU` und `HAILO`. Wird `HAILO` verwendet, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html).<br>- Auf einem PC: `CPU` und `CUDA` (eine NVIDIA-GPU). |
| `deviceIndex` | Gibt den Geräteindex an. Derzeit muss dieser Wert `0` sein. |

> [!NOTE]
> Starten Sie die Anwendung LumiScan AI Object Matching neu, nachdem Sie einen dieser Parameter geändert haben.

## Vollständige Referenz {#complete-reference}

Alle Einstellungen dieser Datei, wie sie ihr JSON-Schema `network-description.schema.json` festlegt, erzeugt für Version 2.1.0 (Beschreibungen aus dem Schema, auf Englisch):

| Einstellung | Typ | Standard | Zulässige Werte | Beschreibung |
| --- | --- | --- | --- | --- |
| `meta` | object |   |   | **Pflichtangabe.** |
| `meta/inputFileType` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/inputFileVersion` | string |   | nicht leer | **Pflichtangabe.** |
| `meta/targetMachine` | string |   | nicht leer |   |
| `meta/programName` | string |   | nicht leer |   |
| `meta/programVersion` | string |   | nicht leer |   |
| `networkType` | string |   |   | **Pflichtangabe.** Current only support 'OrientedObjectDetection' |
| `classList` | object |   |   | [Deprecated] Please rename to 'classes' |
| `thresholdList` | object |   |   | [Deprecated] Please rename to 'thresholds' |
| `classes` | object |   |   | **Pflichtangabe.** Key: Index as string type, Value: Class name |
| `thresholds` | object |   |   | **Pflichtangabe.** Key: Class Name, Value: <0-1 float> threshold value between 0 and 1 |
| `resizedImageShape` | object |   |   | **Pflichtangabe.** |
| `resizedImageShape/height` | number |   |   | **Pflichtangabe.** |
| `resizedImageShape/width` | number |   |   | **Pflichtangabe.** |
| `normalizationMean` | number[] |   | genau 3 Einträge | **Pflichtangabe.** |
| `normalizationStd` | number[] |   | genau 3 Einträge | **Pflichtangabe.** |
| `provider` | string |   | `CPU`, `HAILO` | **Pflichtangabe.** Type of provider, currently only CPU is supported. |
| `deviceIndex` | number |   |   | **Pflichtangabe.** Index of the device to use. If the provider is CPU, this value is ignored. If the provider is GPU, this value is the index of the GPU to use. |
| `spacialNMSRadius` | number |   |   | **Pflichtangabe.** |
| `pathToNetwork` | string |   | nicht leer | **Pflichtangabe.** Path to the network file. The network file must be in ONNX format and the path is relative to the description file. |

[^1]: Informationen zum Hochladen von Daten mit WebDAV finden Sie unter [Daten hochladen mit WebDAV](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html#upload-using-webdav).

# Neues Modul hinzufügen – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/adding-new-module.html

Ein neu trainiertes Modell wird zusammen mit seiner zugehörigen Beschreibungsdatei bereitgestellt. Diese Dateien gehören zusammen und sollten immer als eine Einheit hochgeladen und behandelt werden.

Die folgenden Schritte gelten für ctrlX OS und einen PC; die Screenshots zeigen die Weboberfläche von ctrlX OS.

1. Laden Sie das neue Modell und seine Beschreibungsdatei hoch, wie in [Daten hochladen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html) beschrieben.

   Details zu den Modelldateien finden Sie unter [Ordner models](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html).

2. Öffnen Sie die Anwendungseinstellungen **ai-object-matching.json**:
   - **Auf ctrlX OS:** Klicken Sie mit der linken Maustaste auf den Dateinamen **ai-object-matching.json**. Die JSON-Einstellungen öffnen sich rechts.
   - **Auf einem PC:** Öffnen Sie die Datei im Einstellungsordner mit einem Texteditor.

   ![Einstellungen in ai-object-matching.json mit der aufgeführten neuen Moduldatei](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/application-json-with-new-module.png)

3. Tragen Sie den Namen der hochgeladenen Modulbeschreibungsdatei im Feld `modules` ein.

   ![Feld modules in ai-object-matching.json mit hervorgehobenem Namen der neuen Moduldatei](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/new-module-json-field-detail.png)
   > [!NOTE]
   > Derzeit wird nur ein Modul zur Zeit unterstützt. Entfernen Sie beim Wechsel auf ein neues Modul das vorherige Modul aus dem Feld `modules`.

4. Öffnen Sie die hochgeladene Modulbeschreibungsdatei:
   - **Auf ctrlX OS:** Klicken Sie mit der linken Maustaste auf ihren Dateinamen. Die Moduleinstellungen öffnen sich rechts.
   - **Auf einem PC:** Öffnen Sie die Datei mit einem Texteditor.

   ![Dateiliste mit dem neuen Modul und seinem rechts geöffneten JSON-Inhalt](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/new-module-file-listing-json-panel.png)

5. Prüfen Sie, ob der Parameter `neuralNetworkConfig` auf die neu hochgeladene JSON-Datei der Modellbeschreibung verweist.

   ![Hervorgehobenes Feld neuralNetworkConfig im JSON-Inhalt des neuen Moduls](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/new-module-neural-network-config-detail.png)

6. Prüfen Sie die übrigen Einstellungen, wie in [Konfigurationsdatei eines Moduls](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html) beschrieben.

7. Speichern Sie die Änderungen.

> [!NOTE]
> Starten Sie die Anwendung LumiScan AI Object Matching neu, nachdem Sie die Konfiguration geändert haben.

Ein Modul kann auch über den Data Layer angelegt und aktiviert werden, siehe [Module hinzufügen und entfernen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#adding-and-removing-modules).

# Einstellungen auf dem Data Layer – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html

## Data Layer {#data-layer}

LumiScan AI Object Matching bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-ai-object-matching` an.

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

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan AI Object Matching bietet:

- [ready/request-Handshakes](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html)
- [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.

LumiScan AI Object Matching zeigt die Einstellungen, mit denen es gestartet wurde, auf dem Data Layer unter `hdvisionsystems/lumiscan-ai-object-matching/system/settings`. Sie können sie dort ohne Zugriff auf den Konfigurationsordner lesen und dort ändern: Die Anwendung prüft eine Änderung, speichert sie in ihren Einstellungsdateien und verlangt einen Neustart. `hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute` startet sie neu.

Das funktioniert auf dem ctrlX Data Layer und auf LumiScan Keryx gleich. Der Knoten `system` der LumiScan-Anwendungen ist allgemein in [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html) beschrieben. Wo eine Methode auf den beiden Data Layern unterschiedlich antwortet, sind unten beide Namen angegeben, als ctrlX Data Layer / LumiScan Keryx.

## Was der Knoten zeigt {#what-the-node-shows}

`settings` enthält ein JSON-Dokument, als Text:

- die Einstellungsdatei der Anwendung, `lumiscan-ai-object-matching.json`, wie sie gelesen wurde;
- in ihrer Liste `modules` den Inhalt jeder Modulkonfigurationsdatei anstelle des Dateinamens. `"$file"` nennt die Datei, aus der jedes Modul stammt;
- eine Moduldatei, die nicht gelesen werden konnte, erscheint als `{"$file": ..., "$error": ...}`, wobei `"$error"` den Grund nennt. Das ist auch der Grund, warum das Modul nicht gestartet ist;
- jeder Wert namens `password` wird als `"***"` angezeigt.

Zum Beispiel:

```json
{
  "$schema": "schemas/lumiscan-ai-object-matching.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "lumiscan-ai-object-matching-example-module.json",
      "$schema": "schemas/lumiscan-ai-object-matching-module.schema.json",
      "name": "ood",
      "neuralNetworkConfig": "models/ood-description.json",
      ...
    }
  ],
  "system": { ... }
}
```

Kommentare in den Dateien werden nicht angezeigt.

Der Knoten zeigt die Dateien so, wie die Anwendung sie beim Start gelesen hat. Der Reset eines Moduls liest seine Moduldatei erneut (siehe [Allgemeines Konzept des Handshakes](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html)), und der Knoten zeigt diese Datei dann so, wie sie gelesen wurde. Ein Reset wendet nur einen Teil der Datei an: das Netz und den Abschnitt `stream`. Was `control/subscribe/execute` und `control/unsubscribe/execute` speichern - den Abschnitt `stream` -, wird hier sofort angezeigt.

## Einstellungen ändern {#changing-the-settings}

Lesen Sie `settings`, ändern Sie, was Sie brauchen, und schreiben Sie das gesamte Dokument zurück. Dabei gelten diese Regeln:

- Jedes Modul behält sein `"$file"`. Es muss eine der Moduldateien der Anwendung nennen: Ein Modul kann hier nicht hinzugefügt werden. Wie Sie eines hinzufügen, siehe [Module hinzufügen und entfernen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#adding-and-removing-modules).
- Ein Modul, das aus `modules` weggelassen wird, ist in `lumiscan-ai-object-matching.json` nicht mehr aufgeführt. Seine Datei bleibt, wo sie ist.
- `"***"` für ein Passwort behält das Passwort, das die Datei enthält. Jeder andere Wert ersetzt es.
- Eine Datei, deren Inhalt sich nicht ändert, wird nicht geschrieben. Eine geänderte Datei wird nur dort geändert, wo sich ihr Inhalt geändert hat: Kommentare und Layout bleiben. Ein neuer Schlüssel oder ein neues Listenelement kommt hinter das letzte dort vorhandene; ein entfernter Schlüssel verschwindet mit seiner Zeile, einschließlich eines Kommentars in dieser Zeile. Nur ein Objekt, das Schlüssel sowohl gewonnen als auch verloren hat, oder eine Liste, die ein Element verloren hat, wird neu geschrieben, ohne die Kommentare darin. Die vorherige Datei bleibt daneben als `<file>.bak` erhalten.
- Ein Schlüssel wie `"_comment"` ist Inhalt wie jeder andere, wird also angezeigt und behalten.

Die Anwendung prüft die Änderung, bevor etwas geschrieben wird: Die Konfigurationsdatei der Anwendung und jede geänderte Modulkonfigurationsdatei müssen die Prüfungen bestehen, die die Anwendung beim Start durchführt. Zum Beispiel muss die Netzbeschreibung existieren. Eine Änderung, die die Prüfung ablehnt oder die kein gültiges JSON ist, wird mit `DL_INVALID_VALUE` / `Rejected` beantwortet. Der Grund steht im Log, und nichts wird geschrieben.

Eine Änderung, die nichts schreibt, antwortet mit `DL_OK` / `Ok` und ändert nichts.

### Neustart erforderlich {#restart-required}

Eine gespeicherte Änderung wirkt erst mit dem nächsten Start. Bis dahin läuft die Anwendung mit Einstellungen, die nicht mehr die ihrer Dateien sind, und stellt deshalb ihre Arbeit ein:

- `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` ist `true`;
- `hdvisionsystems/lumiscan-ai-object-matching/system/status-text` nennt die geänderten Dateien;
- jedes Modul meldet Status `-5` (`restartRequired`). Es beantwortet keinen Request, und seine `ready`-Signale sind `false`;
- jede `execute`-Methode eines Moduls antwortet mit `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`. Das schließt `reset` ein, das sonst einen Teil der neuen Einstellungen laden würde;
- ein laufender Bild-Stream stoppt.

Nur ein Neustart beendet diesen Zustand. Ein Reset nicht. Das Log enthält die Meldung auf der Stufe Fehler.

Weitere Änderungen sind in der Zwischenzeit möglich. Nach einer Änderung zeigt `settings` die Dateien wie gespeichert, also das, was der nächste Start lädt, nicht das, womit die Anwendung läuft.

Konnte eine Datei nicht gespeichert werden, antwortet der Schreibvorgang mit `DL_CREATION_FAILED` / `CreationFailed`. Zuvor geänderte Dateien bleiben geändert, sodass die Anwendung trotzdem einen Neustart erfordert. Korrigieren Sie die Dateien und starten Sie dann neu.

## Module hinzufügen und entfernen {#adding-and-removing-modules}

Drei Methoden von `hdvisionsystems/lumiscan-ai-object-matching/system` verwalten Module, jede unter `control/<method>/`, so wie `control/restart`. Jede nimmt die ID des Moduls, den Namen seiner Datei ohne `.json`, in `control/<method>/input/module-id` entgegen:

| Methode | Was sie tut |
| --- | --- |
| `create-module` | Schreibt die Moduldatei `<module-id>.json` mit dem JSON aus `control/create-module/input/content`. Die Anwendung prüft es so, wie sie eine geänderte Moduldatei prüft. Das Modul ist noch nicht aktiv, daher muss nichts neu gestartet werden. Eine vorhandene Datei wird nicht überschrieben: Ändern Sie sie über `settings`. |
| `activate-module` | Fügt `<module-id>.json`, das existieren muss, der Liste `modules` hinzu, nachdem die Anwendung das Modul geprüft hat. Es läuft ab dem nächsten Start, sodass die Anwendung danach einen Neustart erfordert (siehe [Neustart erforderlich](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#restart-required)). |
| `deactivate-module` | Entfernt `<module-id>.json` aus der Liste `modules`. Die Datei bleibt erhalten, sodass `activate-module` sie wieder aufführen kann. Es stoppt mit dem nächsten Start, sodass die Anwendung danach einen Neustart erfordert. |

> [!IMPORTANT]
> AI Object Matching führt ein Modul aus. `activate-module` wird abgelehnt, solange ein Modul aktiv ist: Deaktivieren Sie es zuerst.

Jede Methode meldet auf `control/<method>/output/status-code` und `control/<method>/output/status-text`:

| Code | Bedeutung |
| --- | --- |
| 1 | Erledigt. |
| -2 | Die Eingabe oder das Modul wurde abgelehnt: `status-text` nennt den Grund. Nichts wurde geschrieben. |
| -6 | Eine Datei konnte nicht geschrieben werden. |
| -9 | `activate-module`: Es gibt keine solche Datei. `deactivate-module`: Das Modul ist nicht aktiv. |
| -10 | `create-module`: Die Datei existiert. `activate-module`: Das Modul ist bereits aktiv. |

Die Methode antwortet mit `DL_OK` / `Ok`, wenn sie erledigt ist, mit `DL_INVALID_VALUE` / `Rejected`, wenn sie abgelehnt hat, und mit `DL_CREATION_FAILED` / `CreationFailed`, wenn eine Datei nicht geschrieben werden konnte. Um zum Beispiel das Modul `ood2` hinzuzufügen:

1. Schreiben Sie das JSON des Moduls auf `hdvisionsystems/lumiscan-ai-object-matching/system/control/create-module/input/content` und `ood2` auf `control/create-module/input/module-id`, und rufen Sie dann `control/create-module/execute` auf.
2. Schreiben Sie `ood2` auf `control/activate-module/input/module-id`, und rufen Sie dann `control/activate-module/execute` auf.
3. Rufen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute` auf.

## Anwendung neu starten {#restarting}

`hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute` beendet die Anwendung und startet sie erneut. Sie liest ihre Einstellungsdateien neu ein, was auch von Hand an den Dateien vorgenommene Änderungen anwendet, und beendet `restart-required`.

- **Auf ctrlX OS:** Die Anwendung beendet sich, und ctrlX OS startet sie nach etwa fünf Sekunden erneut.
- **Auf einem PC:** Die Anwendung startet sich selbst erneut, sobald sie alles freigegeben hat, was sie belegt hatte. Sie verwendet dasselbe Programm, dieselben Argumente und denselben Arbeitsordner. Es ist ein neuer Prozess in derselben Konsole, und seine Ausgabe geht dorthin, wohin die des ersten ging.

Die Methode antwortet mit `DL_OK` / `Ok`, sobald der Neustart begonnen hat. Die Knoten der Anwendung verschwinden dann, bis sie wieder läuft: Warten Sie, bis `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` wieder gelesen werden kann.

> [!NOTE]
> Ein Neustart ist nicht an eine Änderung gebunden. Er startet auch eine Anwendung neu, deren Einstellungen sich nicht geändert haben.

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

Auf einem PC schreibt AI Object Matching ein Beispiel seiner Einstellungen in einen Ordner Ihrer Wahl und beendet sich, ohne zu starten:

**Beispiel (Windows)**

```shell
lumiscan-ai-obj-mat --generate-settings C:\work\ai-object-matching-settings
```

Ohne Ordner (`-g` allein) schreibt es in den aktuellen Ordner. Das Beispiel besteht aus der Einstellungsdatei der Anwendung `lumiscan-ai-object-matching.json`, ihrer Beispiel-Moduldatei `lumiscan-ai-object-matching-example-module.json`, der Netzbeschreibung, die dieses Modul benennt, `models\example-network-description.json`, und den fünf Schemas in `schemas\`, mit denen ein Editor sie prüft. Die Modelldatei, die die Beschreibung benennt, `example.onnx`, gehört nicht dazu: Diese müssen Sie selbst bereitstellen. Vorhandene Dateien werden nie überschrieben: Liegt eine davon bereits im Ordner, wird nichts geschrieben, und AI Object Matching nennt sie.

AI Object Matching nennt dann den Ordner, aus dem es seine Einstellungen liest, standardmäßig (Windows) `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-ai-obj-mat\etc\lumiscan-ai-object-matching`. Bearbeiten Sie das Beispiel, kopieren Sie es dorthin, und starten Sie AI Object Matching.

# Daten hochladen – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html

Wie die Einstellungsdateien und die Modelle der neuronalen Netze in den Anwendungsordner gelangen, hängt von der Plattform ab.

## Auf ctrlX OS

> [!NOTE]
> Die meisten Daten können direkt über die ctrlX Web UI hochgeladen werden. Verwenden Sie WebDAV nur, wenn das direkte Hochladen nicht verfügbar ist oder Sie auf die Ordnerstruktur der Anwendung zugreifen müssen.

![ctrlx web ui upload](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/ctrlx-web-ui-upload.png)

Die meisten Dateien können mit dem Upload-Dienst der ctrlX Web UI hochgeladen werden. WebDAV steht als Alternative zur Verfügung, wenn Dateien direkt in die Anwendungsdatenordner hochgeladen werden müssen.

### Hochladen über die ctrlX Web UI

Verwenden Sie den Upload-Dienst der ctrlX Web UI, um das benötigte Modell des neuronalen Netzes und andere unterstützte Dateien hochzuladen.

![ctrlx web ui upload](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/ctrlx-web-ui-upload.png)

### Hochladen über WebDAV {#upload-using-webdav}

So laden Sie Dateien über WebDAV hoch:

1. Gehen Sie auf die Website von WinSCP.

![Download-Website von WinSCP](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/winscp-website.png)

2. Laden Sie die neueste Version von WinSCP herunter und installieren Sie sie.
3. Starten Sie WinSCP.
4. Wählen Sie auf der Anmeldeseite **WebDAV** als **File protocol**.
5. Wählen Sie **TLS/SSL** als **Encryption**.
6. Geben Sie Ihren **Benutzernamen** und Ihr **Passwort** ein.

![WebDAV-Anmeldedialog von WinSCP](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/winscp-login.png)

7. Navigieren Sie zu `/solutions/webdav/appdata`.

![Dialog der Speicherortprofile von WinSCP](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/winscp-location-profiles.png)

8. Die Ordnerstruktur der Anwendung wird im rechten Bereich angezeigt.

![Zweigeteilte Ansicht von WinSCP mit der Ordnerstruktur von appdata über WebDAV](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/winscp-folder-view.png)

Ziehen Sie die benötigten Daten- oder Konfigurationsdateien per Drag-and-drop in den entsprechenden Anwendungsordner.

## Auf einem PC {#upload-on-a-pc}

Auf einem PC sind die Einstellungsdateien und die Modelle der neuronalen Netze gewöhnliche Dateien. Kopieren Sie sie in den Ordner, aus dem die Anwendung ihre Einstellungen liest:

- (Windows) `%APP_RESOURCE_DIR%\etc\lumiscan-ai-object-matching`, wenn die Umgebungsvariable `APP_RESOURCE_DIR` gesetzt ist;
- (Windows) andernfalls `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-ai-obj-mat\etc\lumiscan-ai-object-matching`.

Legen Sie das Modell des neuronalen Netzes und seine Beschreibungsdatei dort im Ordner `models` ab. Starten Sie die Anwendung neu, nachdem Sie eine Datei geändert haben.

# FAQ – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/faq.html

Kurze Antworten auf häufige Fragen zu LumiScan AI Object Matching. Jeder Eintrag verweist auf die Seite mit den Details. Probleme und Fehlermeldungen sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html) beschrieben.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-run-inference`). Um eine Fehlermeldung zu finden, durchsuchen Sie die Seite [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html) danach.

## Erste Schritte

### Was macht LumiScan AI Object Matching, und was benötigt es? {#faq-what-it-does}

- **Antwort:** Es erkennt mit einem trainierten neuronalen Netz Objekte in Bildern und meldet deren Position und Orientierung in Pixelkoordinaten. Es läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC) mit dem ctrlX Data Layer oder auf einem PC (Windows 11 oder Ubuntu 24.04) mit LumiScan Keryx und wird über den Data Layer gesteuert; die Knotenadressen sind auf beiden gleich. Es nimmt selbst keine Bilder auf; es liest Bilder, die eine andere Anwendung veröffentlicht, zum Beispiel der LumiScan Cam Driver (`hdvisionsystems/lumiscan-cam-driver/camera1/output/image`). Das Modell wird mit dem LumiScan Annotation Framework und dem LumiScan Training Framework erstellt.
- **Mehr:** [Beschreibung](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/description.html), [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html)

### Kann ich die TPU-Beschleunigung verwenden, und was sind die Voraussetzungen? {#faq-tpu-acceleration}

- **Betrifft:** ctrlX OS
- **Antwort:** Die TPU-Beschleunigung ist optional. Wird sie verwendet, muss die ctrlX CORE eine TPU enthalten, und es gelten die folgenden Versionen: ctrlX CORE X3 mit App-Version v1.2 oder neuer, ctrlX CORE X7 mit App-Version v1.1 oder neuer und App Hardware Support genau 2.6.2. Mit einer HAILO-TPU ist das Zurückstufen des Hardware Support auf v2.6.2 zwingend erforderlich. Setzen Sie in der JSON-Datei des Modells `provider` auf `HAILO`. Auf einem PC verwenden Sie stattdessen eine NVIDIA-GPU mit `provider` auf `CUDA`.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html), [Release Notes: v1.2.0](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/release-notes/v1-2-0.html)

## Konfiguration

### Wo sind die Konfigurationsdateien? {#faq-config-files}

- **Antwort:** Im Ordner `lumiscan-ai-object-matching`. Auf ctrlX OS öffnen Sie in der Weboberfläche von ctrlX OS **Home** > **Manage app data**, wählen **File View** und öffnen diesen Ordner. Auf einem PC ist es der Einstellungsordner der Anwendung: unter Windows `%APP_RESOURCE_DIR%\etc\lumiscan-ai-object-matching`, oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-ai-obj-mat\etc\lumiscan-ai-object-matching`. Starten Sie die Anwendung neu, nachdem Sie eine Datei geändert haben. Die Einstellungen können auch auf dem Data Layer unter `hdvisionsystems/lumiscan-ai-object-matching/system/settings` gelesen und geändert werden. Der Ordner enthält:
  - `ai-object-matching.json`: Konfiguration der Anwendung (`inputFileType` `LumiScan-CtrlX-AI-Object-Matching`); `modules` listet die Modulkonfigurationsdateien auf.
  - Eine Modulkonfigurationsdatei (zum Beispiel `ai-object-matching-module.json`, `inputFileType` `LumiScan-CtrlX-AI-Object-Matching-Module`). Ihr `name` ist der Netzname, der in der Data-Layer-Adresse verwendet wird, und `neuralNetworkConfig` verweist auf die JSON-Datei des Modells.
  - `models`: die Modelldateien.
- **Mehr:** [Ordnerstruktur von LumiScan AI Object Matching](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/folder-structure.html), [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html)

### Was ist im Ordner models, und welche Modellparameter darf ich ändern? {#faq-model-files}

- **Antwort:** Der Ordner models enthält zwei vom LumiScan Training Framework erzeugte Dateien, die zusammengehören: eine `.onnx`-Datei mit dem trainierten Netz und eine `.json`-Datei mit den Erkennungsparametern. Nur diese JSON-Parameter sollten von Hand geändert werden; starten Sie die Anwendung danach neu:
  - `thresholdList`: Mindestkonfidenz je Klasse, zwischen `0.0` und `1.0` (`1.0` = 100 %).
  - `pathToNetwork`: Pfad zur `.onnx`-Datei, relativ zur JSON-Datei.
  - `provider`: `CPU` oder `HAILO` auf ctrlX OS, `CPU` oder `CUDA` (eine NVIDIA-GPU) auf einem PC.
  - `deviceIndex`: muss derzeit `0` sein.
- **Mehr:** [Ordner models](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/models-folder.html)

### Wie verwende ich ein neu trainiertes Modell? {#faq-new-model}

- **Antwort:** Laden Sie das neue Modell zusammen mit seiner Beschreibungsdatei hoch (sie werden immer als eine Einheit behandelt); auf einem PC kopieren Sie beide in den Ordner `models` des Einstellungsordners. Stellen Sie sicher, dass die Modulkonfigurationsdatei in `modules` von `ai-object-matching.json` aufgeführt ist und dass ihr `neuralNetworkConfig` auf die JSON-Datei des neuen Modells verweist. Prüfen Sie die übrigen Moduleinstellungen, speichern Sie und starten Sie die Anwendung neu.
- **Mehr:** [Neues Modul hinzufügen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/adding-new-module.html), [Daten hochladen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/uploading-data.html)

### Welche Bildformate und Bildquellen werden unterstützt? {#faq-image-source}

- **Antwort:** Eine im Modul konfigurierte externe Bildadresse muss `<address>/data` (Array von `uint8_t`), `<address>/height` und `<address>/width` (`uint32_t`) sowie `<address>/pixel-type` (`Mono8` oder `RGB8`) bereitstellen. Diese Schnittstelle ist für den LumiScan Cam Driver entworfen und getestet; für andere Quellen wird die Funktion nicht garantiert. Ist keine externe Bildadresse konfiguriert, legt das Modul `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image` an, wo Sie das Rohbild schreiben und seine Breite, Höhe und sein Pixelformat setzen. RGB-Daten sind als Höhe, Breite, Kanal angeordnet. Ab v2.2.0 kann ein Modul auch den Bild-Stream des Cam Driver inferieren (experimentell).
- **Mehr:** [Konfigurationsdatei eines Moduls](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/module-configuration-file.html), [Inferenz auf einem Bild-Stream](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html)

## Inferenz ausführen

### Wie starte ich eine Inferenz und erhalte das Ergebnis? {#faq-run-inference}

- **Antwort:** Verwenden Sie den ready/request-Handshake auf `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/`: Warten Sie, bis `ready` `True` ist, merken Sie sich den Wert von `<network name>/output/package-identifier`, setzen Sie `request` auf `True`, warten Sie, bis `ready` `False` ist (die Inferenz läuft bereits), setzen Sie `request` auf `False` und warten Sie, bis `ready` wieder `True` ist. Ist `output/package-identifier` um eins gestiegen, war die Inferenz erfolgreich: Lesen Sie das Ergebnis unter `<network name>/output/result`. `status/code` ist am Ende jeder über den Handshake angeforderten Inferenz `3`, unabhängig davon, ob sie erfolgreich war. Ab v2.1.0 können Sie stattdessen einmal auf `<network name>/control/inference/execute` schreiben, was bis zum Abschluss der Operation blockiert; `status/code` behält dann den Ausgang: `0`, `100001` oder `-1`. Nur ein Prozess darf `request` zur Zeit schreiben.
- **Mehr:** [Inferenz starten](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html), [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference), [Release Notes: v2.1.0](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/release-notes/v2-1-0.html)

### Wie beschränke ich das Ergebnis auf bestimmte Klassen? {#faq-class-filters}

- **Antwort:** Schreiben Sie die Namen der aufzunehmenden Klassen auf `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/class-filters`; lassen Sie das Array leer, um die Filterung zu deaktivieren. Mit der Standard-Klassenzuordnung ist `class_index` im Ergebnis die Position der Klasse im class-names-Array des Netzes. Das Array `instances` kann Objekte verschiedener Klassen enthalten, das SPS-Programm muss also die benötigte Klasse auswählen.
- **Mehr:** [Klassennamen und Klassenfilter](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-class-names-and-filters)

## Ergebnisse in ctrlX PLC Engineering lesen

### Wo bekomme ich das FlatBuffers-Schema für das Ergebnis? {#faq-flatbuffers-schema}

- **Betrifft:** ctrlX OS
- **Antwort:** Der Ergebnisknoten `<network name>/output/result` ist eine FlatBuffers-Nachricht, die durch `object_detection.fbs` beschrieben wird. Die Anwendung kopiert diese Datei bei jedem Start nach `lumiscan-ai-object-matching/schemas/flatbuffers`; laden Sie sie in **Manage app data** mit dem Download-Symbol in der Spalte **Actions** oder über WebDAV herunter. Bearbeiten Sie keine Dateien in `schemas`, da der Ordner bei jedem Start neu angelegt wird. Laden Sie das Schema nach einem Update der Anwendung erneut herunter und importieren Sie es erneut.
- **Mehr:** [Zugriff auf Ergebnisdaten mit FlatBuffers](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html)

### Wie importiere ich das Schema in mein SPS-Projekt? {#faq-import-schema}

- **Antwort:** Sie benötigen ctrlX PLC Engineering 2.6 oder neuer und die Bibliotheken `CXA_Datalayer` und `CXA_Flatbuffers` im **Library Manager**. Klicken Sie im Gerätebaum mit der rechten Maustaste auf **Application**, wählen Sie **Import from FlatBuffers file…** und wählen Sie `object_detection.fbs`. Fehlt **Import from FlatBuffers file…** im Kontextmenü, fehlt die ctrlX-Data-Layer-Bibliothek: Installieren Sie `CXA_Datalayer` über **Tools** > **Library Repository…** und wiederholen Sie den Import.
- **Mehr:** [Die ctrlX-Data-Layer-Bibliothek installieren](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-install-datalayer-library)

### Wie lese ich Position und Score der besten Erkennung? {#faq-read-position-score}

- **Antwort:** Nachdem die Inferenz abgeschlossen und erfolgreich war (Handshake: `output/package-identifier` ist um eins gestiegen; `inference/execute`: `status/code` ist `0`), lesen Sie den Ergebnisknoten mit `DL_ReadNodeValue` und übergeben `GetData` und `GetSize` des `DL_NodeValue` an `getRootAsResult` von `hdv_object_detection2d_Result`. Die Instanzen sind nach Score sortiert (höchster zuerst); `getBestIndex()` liefert immer die beste. Von der Instanz liefert `GetScore()` den Score (0.0 bis 1.0) und `getOrientedBoundingBox()` die Box mit `GetCenterX()`/`GetCenterY()` in Pixeln; der Winkel ist in Grad und kann negativ sein. Die Funktionsbausteine lesen den Puffer an Ort und Stelle, verwenden oder kopieren Sie die Werte also vor dem nächsten Lesen.
- **Mehr:** [Beispiel: Position und Score einer Instanz lesen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-example-instance)

## Fehlerbehebung {#troubleshooting}

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

- [inference/ready bleibt False, oder die Inferenz endet mit Status 100001](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-no-new-external-image)
- [status/code ist nach jeder Inferenz 3](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-status-3-after-inference)
- [Ein Schreibvorgang auf execute wird abgelehnt](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-execute-refused)
- [Eine Inferenz-Anfrage wird mit Status 100002 (StreamActive) beantwortet](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-stream-active)
- [Jedes Modul meldet Status -5 (restartRequired)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-restart-required)
- [Der Ordner schemas existiert nicht](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-schemas-folder-missing)
- [Import from FlatBuffers file… fehlt im Kontextmenü](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#ts-import-command-missing)
- [Nach dem Import erscheint die Meldung "Identifier 'VectorT' not defined"](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-vectort-not-defined)

## Lizenzierung und Support

### Welche Lizenz benötige ich, und was passiert ohne Lizenz? {#faq-licence}

- **Antwort:** Die ctrlX-Lizenz für LumiScan AI Object Matching ist `SWL-W-XCx-OBJxMATCHxHDVSx-V2NN`. Im ctrlX Store für ctrlX OS gekauft, ist sie eine ctrlX-Lizenz und benötigt keinen LumiScan Key. Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund steht im Systemprotokoll. Eine fehlende Lizenz wird als Status `-4` `"MissingLicense"` gemeldet.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html#licence), [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

### Wo finde ich weitere Antworten oder erhalte Support? {#faq-support}

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

# Fehlerbehebung – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html

Diese Seite beginnt mit den allgemeinen Prüfungen, die für jedes Problem gelten. Danach folgen die Probleme, gruppiert nach Inferenz ausführen und Ergebnisse in ctrlX PLC Engineering lesen. Führen Sie zuerst die allgemeinen Prüfungen durch und suchen Sie dann Ihr Symptom.

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

- Lesen Sie den Status des Moduls: `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/code` und `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/text`. Die Bedeutung jedes Codes steht unter [Statuscode-Werte](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values).
- Lesen Sie den Status der Anwendung: `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` und `hdvisionsystems/lumiscan-ai-object-matching/system/status-text`. Ist `restart-required` `true`, siehe [Problem: Jedes Modul meldet Status -5 (restartRequired)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-restart-required).
- Ist ein Modul nicht gestartet, lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/settings`. Eine Moduldatei, die nicht gelesen werden konnte, erscheint dort als `{"$file": ..., "$error": ...}`; `"$error"` nennt den Grund. Siehe [Was der Knoten zeigt](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#what-the-node-shows).
- Lesen Sie das Log. Auf ctrlX OS schreibt die Anwendung ihre Meldungen in das Systemprotokoll von ctrlX OS. Lesen Sie sie im Logbuch der ctrlX-Weboberfläche oder mit `journalctl` (siehe [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html)).
- Prüfen Sie die Lizenz. Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund steht im Systemprotokoll. Eine fehlende Lizenz wird als Status `-4` (`MissingLicense`) gemeldet. Siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html#licence).
- Starten Sie die Anwendung neu, nachdem Sie eine Konfigurationsdatei geändert haben. Auch eine Änderung der Einstellungen auf dem Data Layer wirkt erst mit dem nächsten Start.
- Probleme, die alle LumiScan-Apps gemeinsam haben - eine App oder ein Modul fehlt im Baum, ein Knoten ist „not found", ein Methodenaufruf wird abgelehnt -, sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) im Handbuch LumiScan Keryx beschrieben.

## Inferenz ausführen

### Problem: inference/ready bleibt False, oder die Inferenz endet mit Status 100001 {#faq-no-new-external-image}

**Symptome**

- `<network name>/control/inference/ready` bleibt `False`, Sie können also keine Inferenz anfordern.
- `inference/ready` ist `True`, aber der Request wird nie quittiert: `ready` fällt nicht, nachdem Sie `request` auf `True` gesetzt haben.
- `control/status/code` ist `100001` (`ImageQueueEmpty`). Frühere Versionen meldeten Status `10001` (`noNewExternalImage`); dieser Code wird nicht mehr verwendet.

**Mögliche Ursachen**

- Status `100001`: Das Bild konnte nicht gelesen werden. Der Bildknoten (`input/image` oder die externe Bildadresse) enthält keine Daten oder konnte nicht gelesen werden. Das ist kein Fehler.
- Die Anwendung lädt noch die Konfiguration und richtet das Netz ein.
- Der Bild-Stream des Moduls läuft.
- Es ist keine Lizenz installiert.
- Die Einstellungen wurden auf dem Data Layer geändert, und die Anwendung wartet auf einen Neustart (Status `-5`).
- `ready` ist `True`, aber der Request wird nicht quittiert: Die letzte Inferenz ist fehlgeschlagen, und das Modul hat einen Fehler. Es ignoriert jeden Request außer `reset`.
- Mehr als ein Prozess schreibt `control/inference/request`.

**Diagnose**

1. Lesen Sie `control/status/code` und `control/status/text` des Moduls und schlagen Sie den Code unter [Statuscode-Werte](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values) nach:
   - `1` (`settingUp`): Das Modul wird noch eingerichtet.
   - `100001` (`ImageQueueEmpty`): Das Bild konnte nicht gelesen werden.
   - `100002` (`StreamActive`): Der Bild-Stream läuft, siehe [Problem: Eine Inferenz-Anfrage wird mit Status 100002 (StreamActive) beantwortet](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-stream-active).
   - `-4` (`MissingLicense`): Die Lizenz fehlt.
   - `-5` (`restartRequired`): Ein Neustart ist erforderlich, siehe [Problem: Jedes Modul meldet Status -5 (restartRequired)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-restart-required).
2. Prüfen Sie bei Status `100001` den Bildknoten. Mit einer externen Bildadresse (`externalImagePath` in der Modulkonfigurationsdatei) prüfen Sie, ob `<address>/data`, `<address>/height`, `<address>/width` und `<address>/pixel-type` (`Mono8` oder `RGB8`) Werte haben. Ohne externe Bildadresse prüfen Sie `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image`.
3. Lesen Sie `control/subscribe/output/stream/active`. Erwartet für eine Inferenz auf Anfrage: `false`.
4. Ist `ready` `True`, fällt aber nach Ihrem Request nicht, suchen Sie im Log nach einer fehlgeschlagenen Inferenz.
5. Prüfen Sie, ob nur ein Prozess auf `control/inference/request` zugreift.

**Lösung**

- **Wenn das Bild nicht gelesen werden konnte (Status `100001`):** Stellen Sie ein Bild aus der Bildquelle bereit, zum Beispiel eine Aufnahme mit dem LumiScan Cam Driver, und führen Sie die Inferenz erneut aus. Für ein Bild auf `input/image` schreiben Sie das Rohbild und setzen seine Breite, Höhe und sein Pixelformat, siehe [Inferenz starten](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html). Die Anwendung prüft nicht, ob das Bild neu ist: Ein Bild, das sich seit der letzten Inferenz nicht geändert hat, wird erneut inferiert.
- **Wenn das Modul noch eingerichtet wird:** Warten Sie, bis `inference/ready` `True` ist.
- **Wenn der Bild-Stream läuft:** Stoppen Sie zuerst den Stream, siehe [Problem: Eine Inferenz-Anfrage wird mit Status 100002 (StreamActive) beantwortet](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-stream-active).
- **Wenn keine Lizenz installiert ist:** Installieren Sie die Lizenz, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html#licence).
- **Wenn ein Neustart erforderlich ist (Status `-5`):** Starten Sie die Anwendung neu, siehe [Problem: Jedes Modul meldet Status -5 (restartRequired)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-restart-required).
- **Wenn das Modul nach einer fehlgeschlagenen Inferenz einen Fehler hat:**
  1. Fordern Sie `reset` an (mit dem Handshake auf `control/reset/` oder mit `control/reset/execute`).
  2. Prüfen Sie das Log der Anwendung auf die Ursache.
  3. Fordern Sie die Inferenz erneut an.
- **Wenn mehr als ein Prozess `request` schreibt:** Stellen Sie sicher, dass jeweils nur ein Prozess auf `control/inference/request` zugreift. Andernfalls ist das Ergebnis des Handshakes undefiniert.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten von `control/status/code`, `control/status/text`, `control/inference/ready` und `output/package-identifier` und der Angabe, ob Sie den Handshake oder `control/inference/execute` verwenden.

### Problem: status/code ist nach jeder Inferenz 3 {#faq-status-3-after-inference}

**Symptome**

Nach jeder über den Handshake angeforderten Inferenz ist `control/status/code` `3` (`waitingForClient`), unabhängig davon, ob die Inferenz erfolgreich war.

**Mögliche Ursachen**

- So arbeitet der Handshake: Eine über den Handshake angeforderte Inferenz endet unabhängig von ihrem Ausgang mit Status `3`. `status/code` zeigt nicht, ob sie erfolgreich war.

**Diagnose**

1. Merken Sie sich vor dem Anfordern der Inferenz den Wert von `<network name>/output/package-identifier`.
2. Wenn `inference/ready` wieder `True` ist, lesen Sie `output/package-identifier` erneut. Erwartet: Er ist um eins gestiegen. Er steigt mit jeder erfolgreichen Inferenz um eins, und nur dann (siehe [Ausgang einer Inferenz](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference)).
3. Ist er nicht gestiegen, ist die Inferenz fehlgeschlagen. Fordern Sie die nächste Inferenz an: Fällt `inference/ready` nicht, hat das Modul nach einer fehlgeschlagenen Inferenz einen Fehler.

**Lösung**

- **Wenn `output/package-identifier` um eins gestiegen ist:** Die Inferenz war erfolgreich. Lesen Sie das Ergebnis unter `<network name>/output/result`.
- **Wenn er nicht gestiegen ist, weil das Bild nicht gelesen werden konnte (es gab kein Bild, oder es war leer):** Stellen Sie ein Bild bereit und fordern Sie die Inferenz erneut an.
- **Wenn er nicht gestiegen ist, weil die Inferenz selbst fehlgeschlagen ist:** Das Modul hat einen Fehler und ignoriert jeden Request außer `reset`. Fordern Sie `reset` an und prüfen Sie das Log der Anwendung auf die Ursache.
- **Wenn Sie den Ausgang direkt auf `status/code` lesen möchten:** Starten Sie die Inferenz stattdessen mit `control/inference/execute` (ab v2.1.0). `status/code` behält dann den Ausgang: `0`, `100001` oder `-1`. Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#execute-a-method).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Wert von `output/package-identifier` vor und nach der Inferenz.

### Problem: Ein Schreibvorgang auf execute wird abgelehnt {#faq-execute-refused}

**Symptome**

Ab v2.1.0. Ein Schreibvorgang auf `<network name>/control/<function>/execute` wird mit einem der folgenden Ergebnisse beantwortet. Die Funktion läuft nicht; ein abgelehnter Schreibvorgang wird nie in eine Warteschlange gestellt.

| ctrlX Data Layer | LumiScan Keryx |
| --- | --- |
| `DL_TOO_MANY_OPERATIONS` | `TooManyOperations` |
| `DL_INVALID_OPERATION_MODE` | `InvalidOperationMode` |
| `DL_RESOURCE_UNAVAILABLE` | `ResourceUnavailable` |

**Mögliche Ursachen**

- `DL_TOO_MANY_OPERATIONS` / `TooManyOperations`: Eine andere Funktion des Moduls läuft, über den Handshake oder ein anderes `execute`.
- `DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`: Das `ready`-Signal der Funktion ist `False`, das Modul kann sie also nicht ausführen - zum Beispiel `inference`, solange der Bild-Stream läuft.
- `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`: Die Anwendung wird beendet; oder die Einstellungen wurden auf dem Data Layer geändert und ein Neustart ist erforderlich (Status `-5`); oder das Modul hat nach einer fehlgeschlagenen Inferenz einen Fehler. `reset/execute` wird wegen des Fehlers nie abgelehnt.

**Diagnose**

1. Notieren Sie das genaue Ergebnis des Schreibvorgangs und schlagen Sie es unter [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#execute-a-method) nach (siehe auch [Ein Methodenaufruf wird abgelehnt](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#refused) im Handbuch LumiScan Keryx).
2. Bei `DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`: Lesen Sie den `ready`-Knoten der Funktion (für eine Inferenz `control/inference/ready`) und `control/status/code`. Lesen Sie `control/subscribe/output/stream/active`: `true` bedeutet, dass der Bild-Stream läuft.
3. Bei `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`: Lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required`. `true` bedeutet, dass ein Neustart erforderlich ist.
4. Lesen Sie das Log. Die Apps protokollieren die erste Ablehnung einer Methode, danach höchstens eine Zeile alle zehn Sekunden für dieselbe Methode und dasselbe Ergebnis.

**Lösung**

- **Wenn eine andere Funktion läuft (`DL_TOO_MANY_OPERATIONS` / `TooManyOperations`):** Wiederholen Sie den Aufruf. Der Schreibvorgang gelingt, sobald diese Operation abgeschlossen ist.
- **Wenn das `ready`-Signal `False` ist (`DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`):** Bringen Sie das Modul zuerst in den passenden Zustand; bloßes Wiederholen schlägt weiter fehl. Wiederholen Sie den Aufruf nicht in einer Schleife. Läuft der Bild-Stream, stoppen Sie ihn zuerst, siehe [Problem: Eine Inferenz-Anfrage wird mit Status 100002 (StreamActive) beantwortet](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-stream-active).
- **Wenn ein Neustart erforderlich ist:** Starten Sie die Anwendung neu, siehe [Problem: Jedes Modul meldet Status -5 (restartRequired)](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#faq-restart-required).
- **Wenn das Modul nach einer fehlgeschlagenen Inferenz einen Fehler hat:** Führen Sie `reset` aus (`control/reset/execute`) und wiederholen Sie dann den Aufruf.
- **Wenn die Anwendung beendet wird:** Die Funktion kann nicht laufen. Wenn die Anwendung wieder gestartet ist, können ihre Knoten wieder gelesen werden; wiederholen Sie dann den Aufruf.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem genauen Ergebnis des Schreibvorgangs, der aufgerufenen Funktion und dem Wert von `control/status/code`.

### Problem: Eine Inferenz-Anfrage wird mit Status 100002 (StreamActive) beantwortet {#faq-stream-active}

**Symptome**

Ab v2.2.0 (Bild-Stream, experimentell).

- Nach einem Request auf `control/inference/request` ist `control/status/code` `100002` (`StreamActive`), und der Request wird nicht quittiert.
- `control/inference/ready` ist `False`.
- `control/inference/execute` antwortet mit `DL_INVALID_OPERATION_MODE` (LumiScan Keryx: `InvalidOperationMode`).

**Mögliche Ursachen**

- Das Modul inferiert seinen Bild-Stream. Der Stream und die Inferenz auf Anfrage verwenden dasselbe Netz, deshalb laufen sie nie gleichzeitig (siehe [Inferenz auf Anfrage, während der Stream läuft](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#while-streaming)). Das ist kein Fehler, und kein Reset ist nötig.
- Das Modul ist im Stream-Modus gestartet: `stream.enable` ist in der Modulkonfigurationsdatei `true`. `control/subscribe/execute` speichert `enable`, sodass das Modul nach einem Neustart seinen Stream sofort wieder startet.

**Diagnose**

1. Lesen Sie `control/subscribe/output/stream/active`. `true` bedeutet, dass das Modul seinen Bild-Stream inferiert.
2. Lesen Sie `setting/stream/enable` und `setting/stream/address`: Sie zeigen, was das Modul jetzt anwendet, wie im Abschnitt `stream` der Modulkonfigurationsdatei gespeichert.

**Lösung**

- **Wenn Sie eine Inferenz auf Anfrage benötigen:**
  1. Stoppen Sie den Stream: Schreiben Sie `false` auf `control/subscribe/input/enable` und `true` auf `control/subscribe/execute`. Das wird gespeichert: Das Modul startet wieder so, wie es verlassen wurde.
  2. Prüfen Sie, ob `control/subscribe/output/stream/active` `false` und `control/inference/ready` `True` ist.
  3. Fordern Sie die Inferenz an.
- **Wenn Sie die Ergebnisse des Streams benötigen:** Abonnieren Sie `control/subscribe/output/stream/result` und lesen Sie die Ergebnisse dort.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten von `control/subscribe/output/stream/active` und `setting/stream/enable` und dem Abschnitt `stream` der Modulkonfigurationsdatei.

### Problem: Jedes Modul meldet Status -5 (restartRequired) {#faq-restart-required}

**Symptome**

- Jedes Modul meldet Status `-5` (`restartRequired`). Es beantwortet keinen Request, und seine `ready`-Signale sind `false`.
- `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` ist `true`.
- Jede `execute`-Methode eines Moduls antwortet mit `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`. Das schließt `reset` ein.
- Ein laufender Bild-Stream stoppt.
- Das Log enthält die Meldung auf der Stufe Fehler.

**Mögliche Ursachen**

- Die Einstellungen wurden auf dem Data Layer geändert (`hdvisionsystems/lumiscan-ai-object-matching/system/settings`). Die Änderung ist gespeichert, wirkt aber erst mit dem nächsten Start (siehe [Neustart erforderlich](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#restart-required)).
- `activate-module` oder `deactivate-module` wurde aufgerufen. Die Änderung gilt ab dem nächsten Start.
- Eine Datei konnte nicht gespeichert werden: Der Schreibvorgang antwortete mit `DL_CREATION_FAILED` / `CreationFailed`. Zuvor geänderte Dateien bleiben geändert, sodass die Anwendung trotzdem einen Neustart erfordert.

**Diagnose**

1. Lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required`. Erwartet in diesem Zustand: `true`.
2. Lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/status-text`. Er nennt die geänderten Dateien.
3. Lesen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/settings`. Er zeigt die Dateien wie gespeichert, also das, was der nächste Start lädt.
4. Hat ein Schreibvorgang auf `settings` mit `DL_CREATION_FAILED` / `CreationFailed` geantwortet, suchen Sie im Log nach der Datei, die nicht gespeichert werden konnte.

**Lösung**

Ein Reset beendet diesen Zustand nicht; nur ein Neustart.

- **Wenn die Einstellungen auf dem Data Layer geändert oder ein Modul aktiviert oder deaktiviert wurde:**
  1. Rufen Sie `hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute` auf. Die Methode antwortet mit `DL_OK` / `Ok`, sobald der Neustart begonnen hat. Auf ctrlX OS startet ctrlX OS die Anwendung nach etwa fünf Sekunden erneut.
  2. Warten Sie, bis `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` wieder gelesen werden kann. Erwartet: `false`.
- **Wenn eine Datei nicht gespeichert werden konnte (`DL_CREATION_FAILED` / `CreationFailed`):** Korrigieren Sie die Dateien und starten Sie die Anwendung dann wie oben beschrieben neu.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `system/status-text` und `system/settings`.

## Ergebnisse in ctrlX PLC Engineering lesen

### Problem: Der Ordner schemas existiert nicht {#faq-schemas-folder-missing}

**Symptome**

Auf ctrlX OS existiert in **Manage app data** der Ordner `lumiscan-ai-object-matching/schemas` nicht, Sie können `object_detection.fbs` also nicht aus `lumiscan-ai-object-matching/schemas/flatbuffers` herunterladen.

**Mögliche Ursachen**

- Die Anwendung ist nicht erfolgreich gestartet. Der Ordner `schemas` wird beim Start angelegt, nach der Lizenzprüfung.
- Die Lizenz fehlt. Die Anwendung beendet sich dann kurz nach dem Start.

**Diagnose**

1. Lesen Sie das Systemprotokoll von ctrlX OS im Logbuch der ctrlX-Weboberfläche oder mit `journalctl`. Fehlt die Lizenz, steht der Grund dort.
2. Prüfen Sie, ob die ctrlX-Lizenz `SWL-W-XCx-OBJxMATCHxHDVSx-V2NN` installiert ist.

**Lösung**

- **Wenn die Lizenz fehlt:** Installieren Sie eine gültige Lizenz, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/requirements.html#licence) und [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/troubleshooting.html) im Handbuch LumiScan Lizenzierung. Prüfen Sie dann in **Manage app data**, ob der Ordner `lumiscan-ai-object-matching/schemas/flatbuffers` existiert.
- **Wenn die Anwendung aus einem anderen Grund nicht gestartet ist:** Der Grund steht im Systemprotokoll. Wenden Sie sich an den Support.

Bearbeiten Sie keine Dateien in `schemas`: Die Anwendung löscht den Ordner bei jedem Start und legt ihn neu an.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Meldungen der Anwendung aus dem Systemprotokoll von ctrlX OS.

### Problem: Import from FlatBuffers file… fehlt im Kontextmenü {#ts-import-command-missing}

**Symptome**

Sie klicken in ctrlX PLC Engineering im Gerätebaum mit der rechten Maustaste auf **Application**. Das Kontextmenü enthält **Import from FlatBuffers file…** nicht.

**Mögliche Ursachen**

- Die ctrlX-Data-Layer-Bibliothek `CXA_Datalayer` fehlt.

**Diagnose**

1. Prüfen Sie, ob Sie ctrlX PLC Engineering 2.6 oder neuer verwenden.
2. Prüfen Sie im **Library Manager** des SPS-Projekts, ob `CXA_Datalayer` und `CXA_Flatbuffers` referenziert sind.

**Lösung**

- **Wenn die ctrlX-Data-Layer-Bibliothek fehlt:**
  1. Wählen Sie in der Menüleiste von PLC Engineering **Tools** > **Library Repository…**.

  2. Suchen Sie nach `CXA_Datalayer`, wählen Sie die Bibliothek aus und klicken Sie auf **Open**.

  3. Wiederholen Sie den Import: Klicken Sie mit der rechten Maustaste auf **Application**, wählen Sie **Import from FlatBuffers file…** und wählen Sie `object_detection.fbs`.

     Die Screenshots finden Sie unter [Die ctrlX-Data-Layer-Bibliothek installieren](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-install-datalayer-library).

- **Wenn nach dem Import eine andere Bibliothek fehlt:** Fügen Sie sie im **Library Manager** hinzu.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Version von ctrlX PLC Engineering und den im **Library Manager** aufgeführten Bibliotheken.

### Problem: Nach dem Import erscheint die Meldung "Identifier 'VectorT' not defined" {#faq-vectort-not-defined}

**Symptome**

Nach dem Import von `object_detection.fbs` zeigt der Editor des Funktionsbausteins `hdv_object_detection2d_InstanceTVec` die Meldung `Identifier 'VectorT' not defined` (beobachtet mit ctrlX PLC Engineering 3.6).

![Editor von hdv_object_detection2d_InstanceTVec mit der Meldung Identifier 'VectorT' not defined in der Zeile FUNCTION_BLOCK hdv_object_detection2d_InstanceTVec EXTENDS flatbuffers.VectorT](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/plc-vectort-not-defined.png)

*Abbildung 1. Meldung im Editor von hdv_object_detection2d_InstanceTVec*

**Mögliche Ursachen**

- Der Funktionsbaustein `hdv_object_detection2d_InstanceTVec` erweitert `flatbuffers.VectorT`. Die Version der Bibliothek `CXA_Flatbuffers`, die für ctrlX PLC Engineering 3.6 verfügbar ist (0.1.3.3), enthält diesen Funktionsbaustein nicht.

**Diagnose**

1. Öffnen Sie den Editor von `hdv_object_detection2d_InstanceTVec`. Erwartet: Die Meldung erscheint in der Zeile `FUNCTION_BLOCK hdv_object_detection2d_InstanceTVec EXTENDS flatbuffers.VectorT`.
2. Prüfen Sie im **Library Manager**, welche Version von `CXA_Flatbuffers` das SPS-Projekt referenziert.

**Lösung**

Die Meldung beeinträchtigt das Lesen der Ergebnisse nicht.

- **Wenn die Meldung erscheint:**
  - Verwenden Sie `hdv_object_detection2d_InstanceTVec` nicht in Ihrem Programm. Er wird zum Lesen der Ergebnisse nicht benötigt. Auf einzelne Instanzen greifen Sie mit `getInstances` von `hdv_object_detection2d_Result` zu, siehe [Beispiel: Position und Score einer Instanz lesen](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-example-instance).
  - Stört die Meldung, löschen Sie den Funktionsbaustein `hdv_object_detection2d_InstanceTVec` aus der Anwendung. Kein anderer erzeugter Funktionsbaustein verweist auf ihn.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Version von ctrlX PLC Engineering, der Version von `CXA_Flatbuffers` und der genauen Meldung.

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

Besteht ein Problem weiter, senden Sie die folgenden Informationen an den Support:

- Die Version von LumiScan AI Object Matching.
- Die Plattform: ctrlX OS auf einer ctrlX CORE oder einem ctrlX IPC, mit der Version von ctrlX OS (mit TPU-Beschleunigung auch die Version von App Hardware Support); oder ein PC mit Windows 11 oder Ubuntu 24.04 und LumiScan Keryx.
- Bei Problemen in ctrlX PLC Engineering: die Version von ctrlX PLC Engineering und der Bibliotheken `CXA_Datalayer` und `CXA_Flatbuffers`.
- Das Log der Anwendung. Auf ctrlX OS die Meldungen der Anwendung aus dem Systemprotokoll von ctrlX OS (Logbuch der ctrlX-Weboberfläche oder `journalctl`). Auf einem PC das Log der Anwendung.
- Datum und Uhrzeit des Fehlers.
- Den Status auf dem Data Layer: welchen Data Layer Sie verwenden (ctrlX Data Layer oder LumiScan Keryx; auf einem PC die Data-Layer-Adresse), die Werte von `control/status/code` und `control/status/text` des Moduls, `system/restart-required` und `system/status-text` und bei einem abgelehnten Methodenaufruf das genaue Ergebnis des Schreibvorgangs.
- Die Konfigurationsdateien aus dem Ordner `lumiscan-ai-object-matching`: die Konfigurationsdatei der Anwendung `ai-object-matching.json`, die Modulkonfigurationsdatei und die Modellbeschreibungsdatei (`.json`) in `models`. Alternativ senden Sie den Inhalt von `hdvisionsystems/lumiscan-ai-object-matching/system/settings`: Jeder Wert mit dem Namen `password` erscheint dort als `"***"`.

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 wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

# v1.2.0 - 2025.07.01 – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/release-notes/v1-2-0.html

**Hinzugefügt**

- Funktion: Anwender können Erkennungsergebnisse mit den Funktionen `control/save/control/load/control/list-result-files` exportieren und importieren, um Erkennungsergebnisse aus dem konfigurierten Speicher zu importieren/exportieren.
- Funktion: Volle Kontrolle über GenICam-Features. Zusätzlicher Parameter `initialFeatureFile` in der Einstellung des Kameramoduls, der durch Leerzeichen getrennte `GENICAM_FEATURE_NAME VALUE`-Paare aus einer Textdatei lädt.
- Bedienbarkeit: Unterstützung von internem Speicher, SD-Karte und USB-Speicher
- Bedienbarkeit: Anwender können zu Debug-Zwecken über die Funktion `control/save-result-image` ein Bild speichern.
- Funktion: `input/class-filters` hinzugefügt, um Ergebnisse filtern zu können
- Bedienbarkeit: `settings/class-names` hinzugefügt, um die in den Einstellungen konfigurierten Objektnamen anzuzeigen.

**Fehlerbehebung**

- Hohe CPU-Last beim Beenden des Programms, wenn keine Lizenz erkannt wurde, wodurch die ctrlX CORE blockiert wurde.

> [!NOTE]
> Stellen Sie vor der Verwendung einer Version von LumiScan AI Object Matching sicher, dass die Version der Hardware-Unterstützung (Hardware Support) auf v2.6.2 zurückgestuft ist.
>
> Wird eine HAILO-TPU zur Beschleunigung der Objekterkennung verwendet, ist das Zurückstufen auf Hardware Support v2.6.2 zwingend erforderlich.

# AI Object Matching v2.1.0 – LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/release-notes/v2-1-0.html

## AI Object Matching v2.1.0

**Hinzugefügt** - Ergebnisse können jetzt im JSON-Format gespeichert und geladen werden - Ausführlichere Knotenbeschreibungen - Jede Operation stellt jetzt zusätzlich einen Methodenknoten `<network>/control/<operation>/execute` bereit (inference, reset, load, save, remove, list-result-files, save-result-image). Ein Schreibvorgang darauf führt die Operation einmal aus und blockiert bis zum Abschluss - eine Alternative zum `ready`/`request`-Handshake, der weiterhin funktioniert. Die Ergebnisse erscheinen auf denselben Ausgabeknoten und der Ausgang auf `status/code`; der Data-Layer-Schreibvorgang liefert `DL_TOO_MANY_OPERATIONS`, wenn das Modul mit einer anderen Operation belegt ist (wiederholen Sie den Aufruf, er gelingt, sobald diese abgeschlossen ist), `DL_INVALID_OPERATION_MODE`, wenn das `ready`-Signal der Operation false ist und das Modul sich daher in einem Zustand befindet, in dem sie gar nicht ausgeführt werden kann (Wiederholen hilft nicht), und `DL_RESOURCE_UNAVAILABLE` während des Herunterfahrens oder, bei den abgesicherten Operationen, solange das Modul in einem Fehlerzustand ist und auf ein `reset` wartet.

# LumiScan AI Object Matching

URL: https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Neuronales Netz und seine Modelldatei model.onnx](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/intro/step-1.svg)<br><br>**Ein trainiertes Modell einsetzen.** Mit LumiScan Training auf Ihre Teile trainiert. | ![Gemischte Teile, jedes mit gedrehtem Rahmen, zwei mit Klassenname und Score](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching-de/2.1.0/_images/intro/step-2.svg)<br><br>**Objekte im Bild erkennen.** Jedes mit Klasse, Position, Ausrichtung und Score. | Beispielergebnis<br><br><br><br><br><br><br>Instanzen<br>4<br><br><br>Mitte<br>642, 388 px<br><br><br>Winkel<br>−20.5°<br><br><br>Score<br>0.96<br><br>**Das Ergebnis an die SPS geben.** Nach Score sortiert, bereit für SPS oder Roboter. |

LumiScan AI Object Matching erkennt trainierte Objekte mit neuronalen Netzen in Kamerabildern und meldet jedes mit Klasse, Position, Ausrichtung und Score. Es eignet sich für gemischte, variierende oder schwer beschreibbare Teile, bei denen regelbasiertes Matching an Grenzen stößt. Das Modell trainieren Sie mit LumiScan Training auf Ihre Teile; die App führt es auf ctrlX OS aus, optional auf einer Hailo-TPU, oder auf einem Windows- oder Ubuntu-PC mit NVIDIA-GPU.

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