# LumiScan Calibration 2.0.0.8 – complete documentation

> All pages of the LumiScan Calibration 2.0.0.8 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-calibration-de/2.0.0/

# Beschreibung – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/description.html

LumiScan Calibration ist eine Anwendung, die 2D-Bildkoordinaten in die zugehörigen 3D-Koordinaten auf einer kalibrierten Ebene umrechnet. So lassen sich Positionen, die in Kamerabildern erkannt wurden, auf reale Koordinaten abbilden, zum Beispiel für das Bin Picking mit Robotern, das Ablegen von Objekten und ähnliche Automatisierungsaufgaben.

Die Umrechnung beruht auf Kalibrierdaten, die als TIFF-Datei vorliegen. Die Anwendung verwendet konfigurierbare Transformationsmodule, um Bildkoordinaten auf 3D-Koordinaten abzubilden, und unterstützt verschiedene Interpolationsverfahren zur Bestimmung der Werte zwischen den kalibrierten Punkten.

LumiScan Calibration läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC), wo es aus dem App Store installiert wird, und auf einem PC mit Windows 11 oder Ubuntu 24.04. Die Anwendung wird über JSON-Einstellungsdateien konfiguriert; die Transformationsfunktionen, Eingabekoordinaten, Ausgabekoordinaten und Statusinformationen werden über den Data Layer angesprochen: den ctrlX Data Layer auf ctrlX OS, LumiScan Keryx auf einem PC.

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

Ein Modul rechnet die Punkte um, die ein Programm schreibt, auf Anfrage: über einen ready/request-Handshake oder mit einem einzigen Schreibzugriff auf eine `execute`-Methode. Ab v2.1.0 kann ein Modul auch einen Stream von Punkten umrechnen, sobald sie eintreffen (experimentell): die Punkte eines SPS-Arrays oder die Positionen im Ergebnis einer anderen LumiScan-Anwendung, etwa die Objekte, die AI Object Matching im Bild-Stream einer Kamera findet. Siehe [Einen Stream transformieren (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html).

LumiScan Cockpit zeigt LumiScan Calibration nicht an: Ein Modul erzeugt Koordinaten, kein Bild.

# Voraussetzungen – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html

## Plattform

LumiScan Calibration läuft auf:

- **ctrlX OS** (ctrlX CORE oder ctrlX IPC), wo es aus dem App Store installiert wird. Konfiguration, Steuerung, Koordinaten und Status werden über den ctrlX Data Layer ausgetauscht.
- **einem PC** mit Windows 11 oder Ubuntu 24.04. Konfiguration, Steuerung, Koordinaten und Status werden über LumiScan Keryx ausgetauscht, den Data Layer von HD Vision Systems für PCs.

Die Knotenadressen sind auf beiden gleich. Siehe [ctrlX Data Layer und LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html).

## Lizenz {#licence}

Wie LumiScan Calibration 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-CALIBRATExHDVSx-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 Calibration 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. Geht die Lizenz verloren, während die Anwendung läuft, meldet jedes Modul Status `-4` (`missingLicense`) und führt keine Funktion aus, bis sie wieder vorhanden ist.

## Kalibrierdaten

LumiScan Calibration benötigt für jedes Modul eine Kalibrierdatei im TIFF-Format.

Die TIFF-Datei enthält die 2D-zu-3D-Abbildung, mit der Bildkoordinaten in die zugehörigen 3D-Koordinaten auf der kalibrierten Ebene umgerechnet werden. Die Datei wird aus Kalibrierbildern erzeugt und von HD Vision Systems bereitgestellt.

Wie Sie die benötigten Kalibrierdaten erhalten, lesen Sie unter [TIFF-Datei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/tiff-file.html).

## Streams (experimentell)

Ein Remap-Stream liest das Ergebnis einer anderen Anwendung über die kompilierten Schemata, die LumiScan Calibration mitbringt. Ein Plain-Stream benötigt einen Knoten, der ein float32- oder float64-Array enthält, zum Beispiel eine SPS-Variable. Siehe [Einen Stream transformieren (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html).

# Grundkonzept des Handshakes – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/general-concept-of-handshake.html

Jede Funktion eines Moduls kann mit einem Handshake auf zwei Knoten gestartet werden, `ready` und `request` ([Tabelle 1](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/general-concept-of-handshake.html#table-1-handshake-address)). Eine Funktion kann stattdessen auch mit einem einzigen Schreibzugriff auf ihre `execute`-Methode gestartet werden, siehe [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#execute). Der Handshake aller LumiScan-Anwendungen ist unter [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) beschrieben; LumiScan Calibration folgt seinem Ablauf genau.

**Tabelle 1. Tabelle 1: Grundkonzept des Handshakes: Adressen**

| Adresse | Beschreibung |
| --- | --- |
| `<module address>/control/<function name>/ready` | Schreibgeschützt. Vom Modul gesetzt: `true`, wenn die Funktion gestartet werden kann. |
| `<module address>/control/<function name>/request` | Beschreibbar. Vom Client gesetzt, um die Funktion zu starten. |

`<module address>` ist `hdvisionsystems/lumiscan-calibration/<module name>`, und der Funktionsname ist `transform` oder `reset`. Die Eingaben einer Funktion liegen unter `<module address>/input/` und ihre Ergebnisse unter `<module address>/output/`. Die Knoten jeder Funktion finden Sie in [Tabelle 2](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#table-2-functionality-addresses).

## Eine Funktion ausführen {#functionality-execution}

1. Warten Sie, bis `control/<function name>/ready` `true` ist.
2. Hat die Funktion Eingaben, schreiben Sie sie, zum Beispiel `input/x-coordinate` und `input/y-coordinate`.
3. Setzen Sie `control/<function name>/request` auf `true`.
4. Warten Sie, bis `control/<function name>/ready` `false` ist: Das Modul hat den Request erkannt.
5. Setzen Sie `control/<function name>/request` auf `false`.
6. Das Modul führt die Funktion aus.
7. Wenn die Funktion abgeschlossen ist, ist `control/<function name>/ready` wieder `true`.
8. Lesen Sie `control/status/code` und die Ergebnisse unter `output/`.

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

Gut zu wissen:

- Das Modul wartet darauf, dass `request` zurückfällt, so lange es dauert. Es gibt kein Timeout, weil ein `request`, das danach noch `true` ist, als neuer Request gelesen würde.
- Ein Reset, der angefordert wird, während ein Transform darauf wartet, dass sein `request` zurückfällt, hat Vorrang: Der Transform wird verworfen, und der Reset wird als Nächstes ausgeführt.
- Ein Fehlerstatus bleibt auf `control/status/code` stehen bis zum nächsten Request.

> [!IMPORTANT]
> Stellen Sie sicher, dass nur ein Prozess `control/<function name>/request` schreibt: Ändern ihn mehrere Prozesse unabhängig voneinander, kann das Modul einen Request verpassen. Siehe [Handshake: Regeln](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html#rules).
>
> Ein Programm, das sich nicht mit anderen abstimmen kann, kann stattdessen die `execute`-Methoden verwenden, die einen zweiten Aufruf ablehnen, solange einer läuft.

# Funktionen – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html

Jede Modul-Konfigurationsdatei, die in den Anwendungseinstellungen aufgeführt ist, ist ein **Modul**. Seine Knoten liegen unter `hdvisionsystems/lumiscan-calibration/<module name>/`, wobei der Modulname der Name der Modul-Konfigurationsdatei ohne `.json` in Kleinbuchstaben ist. Ein Modul bietet zwei Funktionen:

- `transform` rechnet 2D-Bildkoordinaten mit der Lookup-Tabelle des Moduls in 3D-Koordinaten um.
- `reset` liest die Modul-Konfigurationsdatei und ihre Lookup-Tabelle erneut ein.

Jede Funktion kann auf zwei Arten gestartet werden, und beide führen zum selben Ergebnis:

- der **ready/request-Handshake**, siehe [Grundkonzept des Handshakes](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/general-concept-of-handshake.html);
- ein einziger Schreibzugriff auf ihre **`execute`**-Methode, siehe [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#execute).

Ein Modul kann auch einen Stream von Punkten transformieren, sobald sie eintreffen, siehe [Einen Stream transformieren (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html).

## Data Layer {#data-layer}

LumiScan Calibration bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-calibration` an.

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

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Calibration 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.

## Adressen {#addresses}

Alle folgenden Adressen beginnen mit `hdvisionsystems/lumiscan-calibration/<module name>/`.

**Tabelle 1. Tabelle 2: Adressen der Funktionen**

| Funktion | Adresse | Zugriff | Bedeutung |
| --- | --- | --- | --- |
| transform | `control/transform/ready` | Schreibgeschützt | `true`, wenn ein Transform angefordert werden kann. |
| transform | `control/transform/request` | Beschreibbar | Fordert einen Transform an, siehe Handshake. |
| transform | `control/transform/execute` | Methode | Führt einen Transform aus und kehrt zurück, wenn er abgeschlossen ist. |
| reset | `control/reset/ready` | Schreibgeschützt | `true`, wenn ein Reset angefordert werden kann. |
| reset | `control/reset/request` | Beschreibbar | Fordert einen Reset an, siehe Handshake. |
| reset | `control/reset/execute` | Methode | Führt einen Reset aus und kehrt zurück, wenn er abgeschlossen ist. |
| status | `control/status/code` | Schreibgeschützt | Der Status der letzten Funktion, siehe [Statuscodes](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#status-code-values). |
| status | `control/status/text` | Schreibgeschützt | Derselbe Status als Text. |
| input | `input/x-coordinate` | Beschreibbar | Das `x` (Pixelspalte) eines Punkts. |
| input | `input/y-coordinate` | Beschreibbar | Das `y` (Pixelzeile) eines Punkts. |
| input | `input/x-coordinate-array` | Beschreibbar | Das `x` jedes von mehreren Punkten. |
| input | `input/y-coordinate-array` | Beschreibbar | Das `y` jedes von mehreren Punkten, so viele wie in `input/x-coordinate-array`. |
| output | `output/x-coordinate`, `output/y-coordinate`, `output/z-coordinate` | Schreibgeschützt | Die 3D-Koordinaten des Punkts auf `input/x-coordinate` und `input/y-coordinate`. |
| output | `output/x-coordinate-array` | Schreibgeschützt | Das `x` jedes Punkts der Eingabe-Arrays, in deren Reihenfolge. |
| output | `output/y-coordinate-array` | Schreibgeschützt | Das `y` jedes Punkts der Eingabe-Arrays. |
| output | `output/z-coordinate-array` | Schreibgeschützt | Das `z` jedes Punkts der Eingabe-Arrays. |
| output | `output/timestamp/seconds` | Schreibgeschützt | Wann der letzte Transform abgeschlossen wurde, in ganzen Sekunden, nach der Uhr des Geräts. |
| output | `output/timestamp/milliseconds` | Schreibgeschützt | Die Millisekunden dieser Zeit, 0 bis 999. |
| output | `output/timestamp/macroseconds` | Schreibgeschützt | Die Mikrosekunden dieser Zeit, 0 bis 999. |
| output | `output/package-identifier` | Schreibgeschützt | Zählt die abgeschlossenen Transforms, beginnend bei `1`. Ein neuer Wert bedeutet neue Ausgaben. |
| output | `output/source` | Schreibgeschützt | Der Modulname. |
| stream | `control/subscribe/…`, `control/unsubscribe/…`, `setting/stream/…` |   | Auf jedem Modul; ohne Abschnitt `stream` streamt ein Modul plain. Siehe [Einen Stream transformieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#addresses). |

Die Anwendung selbst meldet unter `hdvisionsystems/lumiscan-calibration/system/`:

- `found-modules`: die Namen der Module, die sie bedient.
- `status-text`: `"Initialized"`, sobald sie ihre Module bedient, oder warum sie keine bedient.
- `meta/subscription-schema`: was der Knoten, den der Stream eines Moduls abonniert, enthalten darf, als JSON Schema. Siehe [Was eine Quelle enthalten darf](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#subscription-schema).

## Punkte transformieren {#transform}

Ein `transform` rechnet den Punkt auf `input/x-coordinate` und `input/y-coordinate` **und** jeden Punkt aus `input/x-coordinate-array` und `input/y-coordinate-array` um. Lassen Sie die Arrays leer, um nur einen Punkt umzurechnen.

1. Schreiben Sie die Eingaben.
2. Starten Sie den Transform mit dem Handshake oder mit `control/transform/execute`.
3. Wenn er abgeschlossen ist, lesen Sie die Ausgaben. `output/package-identifier` ist um eins gestiegen.

Gut zu wissen:

- `control/transform/ready` ist `false`, solange das Modul keine Lookup-Tabelle hat. Korrigieren Sie die Modul-Konfigurationsdatei oder die TIFF-Datei, und setzen Sie dann das Modul zurück.
- Sind die beiden Eingabe-Arrays unterschiedlich lang, ist der Status `-10001` (`inputXYSizeNotEqual`). Der einzelne Punkt wird umgerechnet, aber die Ausgabe-Arrays, der Zeitstempel und `output/package-identifier` werden nicht geschrieben.
- Ein Punkt außerhalb der Lookup-Tabelle wird nicht als Fehler gemeldet: Das Ergebnis ist ein Wert vom Rand der Tabelle. Halten Sie die Punkte innerhalb des Bildes, für das die Tabelle erstellt wurde.

## Die Einstellungen neu laden {#reset}

Ein `reset` liest die Modul-Konfigurationsdatei und die darin genannte TIFF-Datei erneut ein, und der nächste Transform verwendet sie. Ein Neustart der Anwendung ist nicht nötig. Der Reset liest auch den Abschnitt `stream` erneut ein, einschließlich Quelle und Stream-Modus, und setzt `control/subscribe/input/…` darauf.

- Gelingt der Reset, ist der Status `0` und `control/transform/ready` ist `true`.
- Schlägt er fehl, zum Beispiel weil die TIFF-Datei fehlt, ist der Status `-2` (`invalidSetting`), und das Modul hat **keine** Lookup-Tabelle: `control/transform/ready` bleibt `false`, bis ein Reset gelingt. Das Protokoll nennt den Grund. Das Modul rechnet nicht mit der alten Tabelle weiter, damit eine korrigierte Datei nie mit einer veralteten vermischt wird.
- Ein geänderter Abschnitt `stream` wird mit dem Reset angewendet, siehe [Einen Stream konfigurieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#configuring).
- Das Laden der Beispieltabelle dauerte auf einem PC etwa 30 ms. Eine größere Tabelle oder ein ctrlX CORE können länger brauchen.

## Execute-Methoden {#execute}

`control/transform/execute` und `control/reset/execute` führen ihre Funktion einmal aus und kehren zurück, wenn sie abgeschlossen ist. Schreiben Sie einen beliebigen Wert darauf. Die Funktion verwendet dieselben Eingaben und schreibt dieselben Ausgaben und denselben Status wie der Handshake.

Ob die Funktion überhaupt gestartet werden konnte, meldet der Schreibzugriff selbst. Ein abgelehnter Schreibzugriff wird nie in eine Warteschlange gestellt. Die Ergebnisse sind unten so benannt wie auf dem ctrlX Data Layer; LumiScan Keryx meldet dieselben Ergebnisse unter eigenen Namen, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results):

| Ergebnis | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| OK | Die Funktion wurde ausgeführt. Ihr Ausgang steht auf `control/status/code`. | Lesen Sie den Status und die Ausgaben. |
| `DL_TOO_MANY_OPERATIONS` | Ein anderer Transform oder Reset dieses Moduls läuft, über den Handshake oder ein anderes `execute`. | Wiederholen Sie den Aufruf. Derselbe Schreibzugriff gelingt, sobald die laufende Funktion abgeschlossen ist. |
| `DL_INVALID_OPERATION_MODE` | `transform`: Das Modul hat keine Lookup-Tabelle oder keine Lizenz. `reset`: keine Lizenz. | Wiederholen Sie nicht in einer Schleife. Beheben Sie zuerst die Ursache: Bei fehlender Tabelle korrigieren Sie die Dateien und setzen das Modul zurück. |
| `DL_RESOURCE_UNAVAILABLE` | Die Anwendung wird beendet. | Warten Sie, bis die Anwendung wieder gestartet ist. |

Ein laufender Stream macht ein `execute` nie belegt.

## Statuscodes {#status-code-values}

`control/status/code` und `control/status/text` melden den Ausgang der letzten Funktion. Ein Fehlerstatus bleibt bis zum nächsten Request stehen: Ein Modul, das auf seinen nächsten Request wartet, überschreibt ihn nicht mit `0`. Die Codes `0` bis `-5` sind die Modul-Statuscodes, die alle LumiScan-Anwendungen teilen, siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#module-status); `-10001` ist der eigene Code von LumiScan Calibration.

**Tabelle 2. Tabelle 3: Statuscodes**

| Statuscode | String | Bedeutung |
| --- | --- | --- |
| 0 | `"ready"` | Die letzte Funktion wurde erfolgreich abgeschlossen, und das Modul ist bereit für die nächste. |
| 1 | `"settingUp"` | Das Modul wird initialisiert. |
| 2 | `"running"` | Eine Funktion läuft. |
| 3 | `"waitingForClient"` | Das Modul wartet darauf, dass der Client `request` auf `false` zurücksetzt. |
| -1 | `"undefinedError"` | Ein nicht näher bestimmter Fehler ist aufgetreten. |
| -2 | `"invalidSetting"` | Die Modul-Konfigurationsdatei oder ihre TIFF-Datei konnte nicht geladen werden, sodass das Modul keine Lookup-Tabelle hat. Korrigieren Sie sie, und setzen Sie dann das Modul zurück. |
| -3 | `"invalidInput"` | Ein oder mehrere Eingabewerte sind ungültig. |
| -4 | `"missingLicense"` | Die erforderliche Lizenz ist nicht verfügbar. |
| -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-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#restart-required). |
| -10001 | `"inputXYSizeNotEqual"` | `input/x-coordinate-array` und `input/y-coordinate-array` sind unterschiedlich lang. |

# Einen Stream transformieren (experimentell) – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html

> [!IMPORTANT]
> Der Stream ist **experimentell** (ab v2.1.0). Seine Knoten und Einstellungen können sich noch ändern. Nutzen Sie ihn zur Evaluierung, und prüfen Sie ihn mit Ihrem Aufbau, bevor Sie sich darauf verlassen.

Die Funktion `transform` rechnet die Punkte um, die Ihr Programm schreibt, ein Request nach dem anderen. Ein Stream funktioniert umgekehrt. Das Modul abonniert einen Data-Layer-Knoten, seine **Quelle**, und transformiert **jedes Update** davon, sobald es eintrifft. Die Quelle wird in zwei Teilen benannt: dem **Ordner**, in dem sie liegt (`address`), und dem **Knoten** in diesem Ordner (das `node` des Schritts). Das Modul veröffentlicht das Ergebnis auf `<module name>/control/subscribe/output/stream/points`, mit der Lineage des Updates - woher seine Punkte stammen - und auf `<module name>/control/subscribe/output/stream/plain-points` als einfaches Array, und Ihr Programm abonniert einen davon.

Ein Stream kann seine Punkte auf zwei Arten lesen. Der Schritt in der Liste `onEntry` des Abschnitts `stream` des Moduls gibt an, welche:

- **plain** (kein Schritt oder ein `plain`-Schritt): Der Knoten enthält die Punkte selbst, als ein Array von Zahlen: `x0,y0,x1,y1,…` oder `x0,y0,z0,x1,y1,z1,…`. Ein SPS-Array ist eine typische Quelle.
- **remap** (ein `remap`-Schritt): Der Knoten enthält das Ergebnis einer anderen Anwendung als FlatBuffer - standardmäßig das Bild-Stream-Ergebnis von LumiScan AI Object Matching. Der Schritt benennt die Liste der Elemente darin und die Felder, die das `x` und `y` jedes Elements enthalten.

In beiden Fällen veröffentlicht das Modul ein Tripel pro Punkt, `x,y,z`, in der Reihenfolge der Quelle (siehe [Die Punkte](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#points)). Ein Plain-Stream kann die Punkte eines anderen Moduls lesen, sodass sich Module verketten lassen (siehe [Module verketten](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#chaining)).

Ein Modul hat eine Quelle, die mit der einen Lookup-Tabelle des Moduls transformiert wird. Um zwei Quellen zu transformieren, verwenden Sie zwei Module - auch für zwei Quellen im Bild derselben Kamera, die sich dann dieselbe Lookup-Tabellendatei teilen.

> [!NOTE]
> Ein Remap-Stream transformiert jedes Ergebnis seiner Quelle, unabhängig davon, von welcher Kamera es stammt: Ein Filter liest Felder der Elemente, nicht die Lineage des Ergebnisses. Um die Ergebnisse mehrerer Kameras mit der eigenen Tabelle jeder Kamera zu transformieren, geben Sie jeder Kamera ein eigenes AI-Object-Matching-Modul und jedem davon ein Calibration-Modul.

## Einen Stream konfigurieren {#configuring}

Jedes Modul hat die Stream-Knoten, und jedes Modul kann streamen. Der Abschnitt `stream` seiner Modul-Konfigurationsdatei benennt die Quelle und enthält den Stream-Modus. Seine Liste `onEntry` enthält die Schritte, die jedes Update der Quelle lesen. Ein Modul, dessen Datei keinen Abschnitt `stream` hat, streamt plain, und `control/subscribe/execute` legt den Abschnitt an, wenn es die Quelle speichert.

Der Abschnitt `stream` hat in jeder LumiScan-Anwendung, die einen Stream abonniert, dieselben allgemeinen Schlüssel. Nur die Schritte unterscheiden sich:

```json
"stream": {
    "enable": true,
    "address": "hdvisionsystems/lumiscan-ai-object-matching/example/control/subscribe/output/stream",
    "queueSize": 64,
    "keepLatestOutput": false,
    "onEntry": [
        { "kind": "remap", "node": "result", "array": "instances",
          "x": "oriented_bounding_box.center_x", "y": "oriented_bounding_box.center_y" }
    ]
}
```

| Schlüssel | Erforderlich | Bedeutung |
| --- | --- | --- |
| `enable` | Nein | Stream-Modus: `true` lässt den Stream ab dem Start der Anwendung laufen, ohne dass jemand `control/subscribe/execute` aufruft. Benötigt eine `address`. Weggelassen oder `false`: Der Stream ist aus, bis `control/subscribe/execute` ihn einschaltet. |
| `address` | Mit `enable` | Der Ordner des Knotens, der abonniert werden soll; das `node` des Schritts benennt den Knoten darin. Sie wird genau so verwendet, wie sie geschrieben ist: Die Groß-/Kleinschreibung bleibt erhalten, was ein SPS-Symbol benötigt. Für einen Plain-Stream muss der Knoten ein float32- oder float64-Array enthalten, für einen Remap-Stream einen FlatBuffer des `schema` des Schritts. Weggelassen oder leer, um zur Laufzeit zu abonnieren. Eine Adresse, die mit dem Knoten des Schritts endet - der Knoten selbst, nicht sein Ordner - wird mit dem noch einmal angehängten Knoten abonniert, was fehlschlägt: Das Protokoll warnt und nennt den Ordner, der zu schreiben ist. |
| `tag` | Nein | Das Tag auf den Punkten, die das Modul veröffentlicht: Der Schritt des Moduls in ihrer Lineage trägt es, sodass ein nachfolgender Client sieht, welches Modul sie transformiert hat. Weggelassen oder leer: der Modulname. Siehe [Die Lineage der Punkte](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#lineage). |
| `queueSize` | Nein | Wie viele Updates auf die Transformation warten dürfen: 1 bis 4096, standardmäßig 64. Siehe [Die Warteschlange](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#queue). |
| `keepLatestOutput` | Nein | `true` schreibt die Punkte jedes Updates zusätzlich in die normale Ausgabe des Moduls. Siehe [Die neueste Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#keep-latest-output). Standardmäßig `false`. |
| `onEntry` | Nein | Die Schritte, die auf jedes Update bei seinem Eintreffen angewendet werden, der Reihe nach, jeder ein Objekt mit einem `kind`: ein [`plain`](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#plain)- oder ein [`remap`](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#remap)-Schritt. Derzeit wird ein Schritt verarbeitet; eine Liste mit mehreren ist fehlerhaft. Weggelassen oder leer: ein Plain-Stream mit 2 Zahlen pro Punkt. |
| `onExit` | Nein | Reserviert für Schritte, die auf die Punkte angewendet werden, bevor sie veröffentlicht werden. Wird noch nicht gelesen: Das Modul protokolliert eine Warnung, und die Schritte werden nicht angewendet. |

- Das Hinzufügen, Ändern oder Entfernen des Abschnitts `stream` wird mit einem `reset` des Moduls wirksam. Ein Neustart der Anwendung ist nicht nötig.
- Ein Reset, der ändert, wie die Quelle gelesen wird - ein Schritt von `onEntry` -, startet den Stream im nächsten Zyklus des Moduls neu, etwa 100 ms später. Ein Reset, der nur `enable`, `address`, `tag`, `queueSize` oder `keepLatestOutput` ändert, startet nichts neu: Der laufende Stream folgt.
- Der Abschnitt enthält auch den Stream-Modus und die Quelle, wie sie zur Laufzeit gesetzt wurden: `control/subscribe/execute` und `control/unsubscribe/execute` speichern sie darin. Siehe [In der Modul-Konfigurationsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#kept).
- Ein fehlerhafter Abschnitt `stream` ist eine fehlerhafte Moduldatei: Das Modul meldet Status `-2` (`invalidSetting`) und transformiert nichts, bis er korrigiert und das Modul zurückgesetzt ist. Fehlerhaft sind zum Beispiel Stream-Modus ohne Quelle (`enable` auf `true` gesetzt und keine `address`), ein Schritt mit einem anderen `kind` und ein Schlüssel eines Schritts - `kind`, `node`, `components`, `schema`, `rootType`, `array`, `x`, `y` oder `filters` -, der oben im Abschnitt statt in `onEntry` steht. Das Protokoll nennt den Schlüssel.

Ein älterer Schlüssel `subscriptions`, der mehrere Quellen nach Tag benannte, wird nicht mehr gelesen: Das Modul protokolliert eine entsprechende Warnung. Übertragen Sie seine eine Quelle nach `address` - ihren Ordner - und in das `node` des Schritts.

Um zu sehen, was eine Quelle enthalten darf, lesen Sie `hdvisionsystems/lumiscan-calibration/system/meta/subscription-schema`: siehe [Was eine Quelle enthalten darf](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#subscription-schema).

### Plain: Arrays von Punkten {#plain}

```json
"stream": {
    "enable": true,
    "address": "plc/app/Application/sym/GVL_Vision",
    "onEntry": [
        { "kind": "plain", "node": "aPixelPoints", "components": 3 }
    ]
}
```

Ein Stream ohne Schritt - kein `onEntry` oder ein leeres - ist plain, mit 2 Zahlen pro Punkt, und liest den Knoten `points`: die Punkte eines anderen Calibration-Moduls (siehe [Module verketten](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#chaining)). Ein `plain`-Schritt ist für einen anderen Knoten nötig, etwa ein SPS-Array, oder für 3 Zahlen pro Punkt.

| Schlüssel des Schritts | Erforderlich | Bedeutung |
| --- | --- | --- |
| `kind` | Ja | `"plain"` |
| `node` | Nein | Der Knoten des Ordners, der das Array enthält, zum Beispiel ein SPS-Symbol, `aPixelPoints`. Standardmäßig `points`. |
| `components` | Nein | Die Zahlen pro Punkt: `2` für `x,y` (der Standard), `3` für `x,y,z`. Die Lookup-Tabelle bildet ein Pixel ab, ein `z` wird daher ignoriert. Ein Array, dessen Länge keine ganze Anzahl von Punkten ergibt, wird nicht transformiert und in `statistics/failed-updates` gezählt. |

### Remap: Punkte aus dem Ergebnis einer anderen Anwendung {#remap}

```json
"stream": {
    "address": "hdvisionsystems/lumiscan-ai-object-matching/<module name>/control/subscribe/output/stream",
    "onEntry": [
        {
            "kind": "remap",
            "node": "result",
            "array": "instances",
            "x": "oriented_bounding_box.center_x",
            "y": "oriented_bounding_box.center_y",
            "filters": [
                { "field": "class_index", "anyOf": [0, 2] },
                { "field": "score", "min": 0.5 }
            ]
        }
    ]
}
```

Dieses Beispiel transformiert den Mittelpunkt jeder Box, die AI Object Matching in seinem Bild-Stream findet, für die Klassen `0` und `2` mit einem Score von mindestens `0.5`. Es liest den Knoten `result` des Stream-Ordners des AI-Moduls, einen FlatBuffer des Standardschemas `stream_detections`.

Ein Stream-Ergebnis wie dieses enthält zwei Dinge: seine `lineage` und das Ergebnis selbst - dasselbe Ergebnis, das die Anwendung in ihre normale Ausgabe schreibt. Der Schritt liest innerhalb des Ergebnisses, `array` ist also der Pfad wie in der normalen Ausgabe: `instances`, die Liste der Funde von AI Object Matching. Die Punkte, die das Modul veröffentlicht, tragen die Lineage des AI-Ergebnisses - das Kamerabild, auf dem es inferiert wurde - mit dem eigenen Schritt des Moduls ergänzt.

Das Beispielmodul, das die Anwendung mitbringt, `example`, hat einen solchen Schritt ohne Filter. Es liest das Beispielmodul von AI Object Matching, ebenfalls `example`, von seinem Start an. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).

| Schlüssel des Schritts | Erforderlich | Bedeutung |
| --- | --- | --- |
| `kind` | Ja | `"remap"` |
| `node` | Nein | Der Knoten des Ordners, der den FlatBuffer enthält. Standardmäßig `result`: das Stream-Ergebnis einer LumiScan-Anwendung in ihrem Ordner `control/subscribe/output/stream`. |
| `schema` | Nein | Welchen FlatBuffer der Knoten enthält; standardmäßig `stream_detections`, das Stream-Ergebnis von AI Object Matching. Entweder der Name eines Schemas, das die Anwendung mitbringt, oder der Pfad einer kompilierten Schemadatei (`.bfbs`), relativ zur Modul-Konfigurationsdatei. Die mitgelieferten Schemata, jeweils mit ihrem `array`:<br><br>\* die Stream-Ergebnisse (Knoten `result`): `stream_detections` (AI Object Matching, `instances`), `stream_template_matches` (Template Finder, `matches`), `stream_object_matches` (Object Finder, `matches`), `stream_areas` (Area Detector, `blobs`), `stream_codes` (die Code Reader, `results`), `stream_texts` (Text Reader, `words`); \* die normalen Ausgaben: `object_detection` (`output/result` von AI Object Matching, `instances`), `template_match_result`, `object_find_result`, `area_detect_result`, `code_detect_result` und `text_read_result`, mit denselben Listen; \* die Punkte eines anderen Calibration-Moduls: `stream_points` (Knoten `points`, `array` `points`, `x` und `y` mit den Namen `x` und `y`). |
| `rootType` | Nein | Die Tabelle an der Wurzel des Buffers, mit ihrem Namespace, zum Beispiel `hdv.object_detection2d.Result`. Weglassen, um den eigenen Root-Typ des Schemas zu verwenden. |
| `array` | Nein | Der Pfad zur Liste, deren Elemente die Punkte sind, zum Beispiel `instances`. In einem Stream-Ergebnis beginnt er innerhalb des Ergebnisses, wie in der normalen Ausgabe. Weggelassen: keine Liste - das Ergebnis selbst ist das eine Element, und jedes Update liefert einen Punkt, oder keinen, wenn ein Filter es ablehnt. Siehe [Ein Punkt pro Update](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#one-point). |
| `x`, `y` | Ja | Der Pfad innerhalb eines Elements zu seinem `x` und seinem `y`, zum Beispiel `oriented_bounding_box.center_x`. |
| `filters` | Nein | Nur die Elemente, die jeden Filter passieren, werden zu Punkten. Jeder Filter hat ein `field` (ein Pfad innerhalb eines Elements zu einer Zahl) und mindestens eines von `anyOf` (eine Liste von Werten, von denen das Feld einem gleichen muss), `min` und `max` (einschließende Grenzen). Ein Integer-Feld wird als Integer verglichen. |

Ein Pfad ist eine Liste von Feldnamen, verbunden mit `.`, so wie das Schema sie benennt. Jeder Schritt außer dem letzten muss zu einer Struktur führen, der letzte zu einer Zahl. Das Modul prüft jeden Pfad beim Start des Streams gegen das Schema. Passt einer nicht, startet der Stream nicht, und das Protokoll sagt, welcher Schritt falsch ist. Zwei Fehler werden mit der Korrektur genannt:

- ein `array`, das mit dem eigenen Feld des Stream-Ergebnisses beginnt, `result.instances`: Das Ergebnis wird bereits gelesen, schreiben Sie `"array": "instances"`;
- kein `array`, während `x` oder `y` nur in den Elementen einer Liste des Ergebnisses zu finden ist: Benennen Sie die Liste, zum Beispiel `"array": "instances"`.

#### Ein Punkt pro Update {#one-point}

Ein Ergebnis, das keine Liste ist - eine Pose, eine Position -, liefert einen Punkt pro Update. Lassen Sie `array` weg, und benennen Sie die Felder innerhalb des Ergebnisses:

```json
{ "kind": "remap", "schema": "my_result.bfbs", "node": "result", "x": "pose.x", "y": "pose.y" }
```

Die Filter gelten für dieses eine Element: Ein Update, das sie nicht passiert, wird ohne Punkte veröffentlicht.

Gut zu wissen:

- Ein Feld, das das Element nicht setzt, wird als sein Standardwert im Schema gelesen, wie bei jedem FlatBuffer-Reader.
- Fehlt eine Struktur auf einem Pfad in einem Element, wird der Punkt als `NaN,NaN,NaN` veröffentlicht, und ein Filter auf diesem Pfad lehnt das Element ab.
- Ein Update, das kein gültiger Buffer des angegebenen Typs ist, wird nicht transformiert. Es wird in `statistics/failed-updates` gezählt, und das erste wird in das Protokoll geschrieben.

## Adressen {#addresses}

Alle folgenden Adressen beginnen mit `hdvisionsystems/lumiscan-calibration/<module name>/`. Jedes Modul hat sie. 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 Modul-Konfigurationsdatei und wendet sie dann an: Der Stream folgt im nächsten Zyklus des Moduls, ohne Neustart. Siehe [Zur Laufzeit abonnieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die Quelle, die `control/unsubscribe/input/address` nennt, was auch den Stream-Modus beendet, und speichert das. |

**Tabelle 2. Eingaben**

| Adresse | Typ | Beim Start | Bedeutung |
| --- | --- | --- | --- |
| `control/subscribe/input/enable` | bool | `stream.enable` oder `false` | `true` lässt den Stream laufen; `false` stoppt ihn. |
| `control/subscribe/input/address` | string | `stream.address` oder leer | Der Ordner des Knotens, der abonniert werden soll, genau wie geschrieben. Das `node` des Schritts benennt den Knoten darin. |
| `control/subscribe/input/tag` | string | `stream.tag` oder leer | Das Tag auf den Punkten, die das Modul veröffentlicht, in ihrer Lineage. Leer: der Modulname. |
| `control/subscribe/input/queue-size` | uint32 | `stream.queueSize` oder 64 | Wie viele Updates auf die Transformation warten dürfen, 1 bis 4096. Siehe [Die Warteschlange](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#queue). |
| `control/subscribe/input/keep-latest-output` | bool | `stream.keepLatestOutput` oder `false` | `true` schreibt die Punkte jedes Updates zusätzlich in die normale Ausgabe. Siehe [Die neueste Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.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: Nur `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.

**Tabelle 3. Ausgaben**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/output/stream/active` | bool | `true`, solange der Stream läuft. |
| `control/subscribe/output/stream/points` | flatbuffers (`stream_points`) | Die Punkte jedes Updates, transformiert, mit ihrer Lineage. Abonnieren Sie ihn, um jedes zu erhalten. Ein Lesen liefert das neueste. Siehe [Die Punkte](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#points). |
| `control/subscribe/output/stream/plain-points` | float32-Array | Dieselben Punkte als einfaches Array, `x0,y0,z0,x1,y1,z1,…`, ohne die Lineage: für einen Client, der keinen FlatBuffer lesen kann, etwa eine SPS. |
| `control/subscribe/output/stream/statistics/…` | uint64 | Zähler des aktuellen oder letzten Streams, siehe [Die Statistik lesen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.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 jetzt anwendet, wie im Abschnitt `stream` gespeichert. |
| `setting/settings-hash` | string | Der Hash dessen, womit die Punkte transformiert werden, als 16 Hexadezimalziffern. Siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#settings-hash). |

Sofern `keep-latest-output` nicht gesetzt ist, werden die Punkte des Streams nur auf `control/subscribe/output/stream/points` und `control/subscribe/output/stream/plain-points` veröffentlicht, und die normalen Ausgaben behalten das Ergebnis des letzten Transforms auf Anfrage.

### Was eine Quelle enthalten darf {#subscription-schema}

`hdvisionsystems/lumiscan-calibration/system/meta/subscription-schema` (string, schreibgeschützt, experimentell) beschreibt, was der Knoten, den ein Modul abonniert, enthalten darf, als JSON Schema (draft-04) der JSON-Form des Knotens. Es führt drei Arten auf, von denen jede passt (`anyOf`):

- ein einfaches Array von Zahlen - ein `plain`-Schritt oder keiner;
- ein `stream_points` - die Punkte eines anderen Calibration-Moduls, plain gelesen;
- ein `stream_detections` - das Stream-Ergebnis von AI Object Matching, gelesen von einem `remap`-Schritt mit dem Standardschema.

Es ist für jedes Modul gleich und sagt daher nicht, welche Art ein Modul liest: Das sagt sein `onEntry`-Schritt. Die Beschreibungen darin stammen aus den FlatBuffer-Schemata. Ein Feld eines FlatBuffers wird so gezeigt, wie das JSON von `flatc --strict-json` es darstellt: ein Enum über seinen Namen, eine Struktur als Objekt.

## Einen Stream ausführen {#running}

1. Abonnieren Sie `control/subscribe/output/stream/points` oder `control/subscribe/output/stream/plain-points` für das einfache Array.
2. 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 werden Updates der Quelle transformiert.
3. Zum Stoppen schreiben Sie `false` auf `control/subscribe/input/enable` und `true` auf `control/subscribe/execute`.

Gut zu wissen:

- Der Stream-Modus wird im Abschnitt `stream` gespeichert, bevor er wirkt: Nach einem Neustart der Anwendung streamt das Modul wieder, oder nicht, wie zuvor. Niemand muss die Methode erneut aufrufen.
- Der Stream läuft nur, solange die Lizenz vorhanden ist.
- Kann der Stream nicht starten, weil ein Remap-Pfad nicht zum Schema passt, bleibt `control/subscribe/output/stream/active` `false`, und der Grund wird in das Protokoll geschrieben. Es wird nicht erneut versucht, bis das Modul zurückgesetzt oder der Stream-Modus mit `control/subscribe/execute` aus- und wieder eingeschaltet wird.
- Eine Quelle, die nicht abonniert werden kann, zum Beispiel ein Knoten, der noch nicht existiert, hindert den Stream nicht am Laufen: Es wird alle 5 Sekunden erneut versucht, und der erste Fehlschlag wird in das Protokoll geschrieben.
- Das Transformieren auf Anfrage funktioniert weiter, während der Stream läuft: Der `transform`-Handshake und `control/transform/execute` werden wegen des Streams nie abgelehnt.
- Ein `reset` ersetzt die Lookup-Tabelle sofort, auch für den laufenden Stream: Das nächste Update wird mit der neuen Tabelle transformiert. Schlägt der Reset fehl, hat das Modul keine Tabelle, und der Stream veröffentlicht `NaN` für jeden Punkt, bis ein Reset gelingt.

## Die Warteschlange {#queue}

Die Updates der Quelle warten in einer Warteschlange, in der Reihenfolge ihres Eintreffens, und werden nacheinander transformiert. Ein Update wird nur verworfen, wenn die Warteschlange voll ist - `queueSize` Updates, standardmäßig 64, warten bereits: Dann geht das älteste verloren und wird in `statistics/skipped-updates` gezählt.

Eine größere `queueSize` übersteht längere Lastspitzen, ohne ein Update zu verwerfen; aktualisiert die Quelle aber über längere Zeit schneller, als das Modul transformiert, sind die veröffentlichten Punkte älter: bis zu `queueSize` Updates im Rückstand. Eine kleinere hält die Punkte aktuell und verwirft mehr.

Eine geänderte Warteschlangengröße gilt sofort, ohne Neustart des Streams. Schrumpft sie unter die Zahl der bereits wartenden Updates, werden die ältesten davon verworfen und als übersprungen gezählt.

## Zur Laufzeit abonnieren {#subscribing}

Eine SPS oder ein anderer Client ändert die Quelle und den 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 Quelle `control/subscribe/input/address`, ihren Ordner (der Knoten darin bleibt der des Schritts); zum Starten oder Stoppen `control/subscribe/input/enable`; für ein anderes Tag auf den Punkten `control/subscribe/input/tag`.
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 im nächsten Zyklus des Moduls. Eine andere Adresse ersetzt die Quelle - ein vorheriges Unsubscribe ist nicht nötig -, und die Updates, die die alte Quelle noch wartend hatte, werden verworfen und als übersprungen gezählt. Die Warteschlangengröße und `keep-latest-output` gelten, ohne erneut zu abonnieren, ebenso das Tag: Die ab dann veröffentlichten Punkte tragen es.

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 Punkte 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 `/` an einem der Enden einer Adresse spielt keine Rolle.

Die Methoden antworten wie folgt. Wo ein Ergebnis nur einen Namen hat, ist es der Name auf dem ctrlX Data Layer; LumiScan Keryx meldet dasselbe Ergebnis unter eigenem Namen, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results).

| Ergebnis | Wann |
| --- | --- |
| `DL_OK` | Erledigt. |
| `DL_INVALID_VALUE` (ctrlX Data Layer), `Rejected` (LumiScan Keryx) | `control/subscribe`: `enable` ist `true` und die Adresse ist leer, oder die Warteschlangengröße liegt nicht zwischen 1 und 4096. `control/unsubscribe`: Die Adresse ist nicht die Quelle, oder es gibt keine Quelle. Nichts hat sich geändert. |
| `DL_CREATION_FAILED` | Die Änderung konnte nicht in der Modul-Konfigurationsdatei gespeichert werden: Die Datei konnte nicht gelesen oder geschrieben werden. Nichts hat sich geändert: Der Stream bleibt, wie er war. Die Antwort und das Protokoll nennen den Grund. |
| `DL_RESOURCE_UNAVAILABLE` | Die Einstellungen wurden auf `system/settings` bearbeitet, und die Anwendung wartet auf einen Neustart. |

## In der Modul-Konfigurationsdatei gespeichert {#kept}

Stream-Modus und Quelle sind Einstellungen des Moduls, im Abschnitt `stream` seiner Konfigurationsdatei. `control/subscribe/execute` und `control/unsubscribe/execute` speichern `enable`, `address`, `tag`, `queueSize` und `keepLatestOutput` dort, bevor sie sie anwenden: Können sie nicht gespeichert werden, antwortet die Methode mit `DL_CREATION_FAILED`, und nichts ändert sich. Nach einem Neustart abonniert das Modul dieselbe Quelle und startet, wenn `enable` `true` ist, seinen Stream sofort.

Das Speichern ändert nur diese Werte: Der Rest der Datei bleibt, wie er war, einschließlich Kommentaren und der Schritte von `onEntry`. Eine Datei ohne Abschnitt `stream` erhält einen, mit diesen Werten und ohne Schritt: ein Plain-Stream.

Ein Reset liest die Datei erneut ein und setzt die Eingaben darauf: Eine Änderung, die Sie von Hand in der Datei vornehmen, wird mit dem nächsten Reset wirksam.

## Die neueste Ausgabe behalten {#keep-latest-output}

Mit gesetztem `keep-latest-output` werden die Punkte jedes Updates zusätzlich in die normale Ausgabe des Moduls geschrieben, so wie ein Transform auf Anfrage sie schreibt: `output/x-coordinate-array`, `output/y-coordinate-array` und `output/z-coordinate-array`, `output/timestamp` und `output/package-identifier`, weitergezählt von den Transforms auf Anfrage. Ein Client, der die normale Ausgabe liest - zum Beispiel ein SPS-Programm, das für die Funktion `transform` geschrieben wurde -, sieht dort dann die neuesten Punkte des Streams. Ein Punkt, der nicht transformiert werden kann, ist auch dort `NaN`.

Es kostet eine Kopie der Punkte jedes Updates und ist deshalb standardmäßig aus. Die Punkte auf `control/subscribe/output/stream/points` werden zuerst veröffentlicht.

## Die Punkte {#points}

`control/subscribe/output/stream/points` enthält eine FlatBuffers-Tabelle vom Typ `stream_points`, auf dem Data Layer registriert als `types/hdvisionsystems/lumiscan-calibration/stream_points`. Ihr kompiliertes Schema ist als `bfbs/stream_points.bfbs` installiert.

| Feld | Bedeutung |
| --- | --- |
| `points` | Je ein `x`, `y`, `z` (float32) pro Punkt des Updates, in dessen Reihenfolge. |
| `invalid` | Wie viele der Punkte nicht transformiert werden konnten. |
| `lineage` | Woher das Update stammt, siehe [Die Lineage der Punkte](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#lineage). |

`control/subscribe/output/stream/plain-points` veröffentlicht dieselben Punkte als `x0,y0,z0,x1,y1,z1,…`, direkt nach `control/subscribe/output/stream/points`.

- Der i-te Punkt ist der i-te Punkt des Updates. Ein Punkt, der nicht transformiert werden kann, wird an seiner Stelle als `NaN` veröffentlicht, sodass die Reihenfolge erhalten bleibt. Ein Punkt kann nicht transformiert werden, wenn er außerhalb der Lookup-Tabelle liegt oder wenn das Modul keine Tabelle hat.
- Ein Update ohne Punkte wird ohne Punkte veröffentlicht.
- `z` ist der Wert der Lookup-Tabelle. Ein `z` in einer Plain-Quelle mit `components` `3` wird ignoriert.

> [!NOTE]
> Ein Punkt außerhalb der Lookup-Tabelle wird nur vom Stream als `NaN` veröffentlicht. Auf Anfrage liefert die Funktion `transform` für einen solchen Punkt einen Wert vom Rand der Tabelle, ohne Fehler, wie schon immer. Halten Sie die Punkte, die Sie anfragen, innerhalb des Bildes, für das die Tabelle erstellt wurde.

### Module verketten {#chaining}

`control/subscribe/output/stream/points` eines Moduls kann die Quelle eines Plain-Streams in einem anderen Modul sein. Das zweite Modul liest ihn als `x,y,z`-Punkte, unabhängig von seinem `components`, transformiert das `x` und `y` jedes Punkts und ignoriert das `z`. Seine Punkte tragen die Lineage des ersten Moduls mit seinem eigenen Schritt ergänzt. `control/subscribe/output/stream/plain-points` funktioniert ebenfalls als Quelle, mit `components` `3`, aber seine Punkte beginnen eine eigene Lineage.

### Die Lineage der Punkte {#lineage}

`lineage.steps` listet auf, woher die Punkte eines Updates stammen, Ursprung zuerst:

- Eine Quelle, die eine Lineage trägt - `control/subscribe/output/stream/result` von AI Object Matching, `control/subscribe/output/stream/points` eines anderen Moduls -, gibt ihre Schritte weiter: zuerst der Schritt der Kamera (`producer` die Adresse der Kamera, `tag` das Tag des Cam-Driver-Moduls, `run` und `sequence` die Stelle des Bildes im Stream der Kamera), dann der des AI-Moduls, mit dem Tag des AI-Moduls.
- Eine Quelle, die keine trägt - ein SPS-Array -, erhält einen für sie erzeugten Schritt, markiert als `synthesized`: Sein `producer` ist die Adresse des Knotens, Ordner und Knoten; er hat kein `tag`; seine `sequence` ist der eigene Zähler des Moduls seit dem Start des Streams. Auf LumiScan Keryx ist die `sequence` die Sequenznummer des Data Layers für das Update, wo es eine gibt, sonst der eigene Zähler des Moduls.
- Der eigene Schritt des Moduls kommt zuletzt: `producer` ist die Adresse des Moduls, `hdvisionsystems/lumiscan-calibration/<module name>`; `tag` das Tag des Moduls (`stream.tag`) oder der Modulname, wenn es keines hat; `run`, wann der Stream des Moduls gestartet wurde; `sequence` die Nummer des Updates im Lauf; `settings_hash`, siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Updates bis zur Veröffentlichung der Punkte.

Das `tag` jedes Schritts sagt, welches Modul das Update dort verarbeitet hat - der eigene Name des Moduls oder das Tag, das es erhalten hat. Geben Sie zwei gleichnamigen Modulen in verschiedenen Anwendungen, oder einem Modul, dessen Name wenig aussagt, ein Tag, das sagt, was es in Ihrer Linie tut.

Eine Quelle, die geändert wird, während der Stream läuft, behält den Lauf des Moduls: Die Updates der neuen Quelle werden weitergezählt, und der `producer` ihres ersten Schritts benennt sie.

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

`setting/settings-hash` und der `settings_hash` des Modulschritts identifizieren, womit die Punkte transformiert werden. Der Hash ändert sich, wenn sich eines davon ändert:

- die Einstellungen der Modul-Konfigurationsdatei - außer dem `name` des Transforms; `enable`, `address`, dem `node` seines Schritts, `tag`, `queueSize` und `keepLatestOutput` des Streams, die die Updates schalten, auswählen, takten und markieren, statt ihre Punkte zu ändern; und seinem `onExit`, das noch nicht gelesen wird;
- die Lookup-Tabelle (`relativePathToTiff`) nach ihrem Inhalt - eine neue Tabelle unter dem alten Dateinamen ist ein neuer Hash; und das `schema` eines Remap-Schritts nach seinem Inhalt - dasselbe Schema unter anderem Namen ist derselbe Hash;
- die Version der Anwendung.

Ein Reset liest sie erneut ein. Wenn ein Hash zum ersten Mal auftritt, schreibt das Modul die Einstellungen, für die er steht, nach `settings-history/<module name>-<hash>.json` im Konfigurationsordner der Anwendung, sodass ein Hash, der in der Lineage der Punkte gefunden wird, später nachgeschlagen werden kann.

> [!NOTE]
> Die Punkte tragen nur den Hash. Ein anderer Hash sagt, dass sich etwas geändert hat, womit sie transformiert werden, nicht was. Um es herauszufinden, vergleichen Sie die beiden Dateien in `settings-history`, die die Hashes benennen, von Hand.

## Die Statistik lesen {#statistics}

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

| Zähler | Bedeutung |
| --- | --- |
| `elapsed-ms` | Millisekunden seit dem Start des Streams. Teilen Sie die anderen Zähler dadurch, um Raten zu erhalten. |
| `received-updates` | Updates der Quelle, die eingetroffen sind. |
| `transformed-updates` | Updates, die transformiert und auf `control/subscribe/output/stream/points` und `control/subscribe/output/stream/plain-points` veröffentlicht wurden. |
| `skipped-updates` | Updates, die unverarbeitet verworfen wurden, weil die Warteschlange voll war (`queueSize`, standardmäßig 64): Das Modul konnte mit der Quelle nicht Schritt halten. Das älteste wartende Update wird zuerst verworfen. Außerdem die Updates, die warteten, als die Quelle ersetzt wurde oder als die Warteschlangengröße unter ihre Zahl schrumpfte. |
| `failed-updates` | Updates, die nicht transformiert werden konnten: nicht der erwartete Typ oder die erwartete Länge, oder kein gültiger Buffer. Das erste wird in das Protokoll geschrieben. |
| `lost-updates` | Updates, die verworfen wurden, bevor sie eintrafen. Für eine Quelle, die eine Lineage trägt, ermittelt aus Lücken in der `sequence` des Schritts ihres Produzenten innerhalb eines Laufs. Auf LumiScan Keryx, für ein einfaches Array, aus Lücken in den Sequenznummern des Data Layers. Eine neue Quelle beginnt die Zählung neu. |
| `points` | Transformierte Punkte, alle Updates zusammen. |
| `invalid-points` | Davon die Punkte, die als `NaN` veröffentlicht wurden. |
| `transform-us` | Mikrosekunden, die alle Transformationen gedauert haben, summiert. Teilen Sie durch `transformed-updates` für den Mittelwert. |

## Was ein Stream empfängt {#data-layers}

`control/subscribe/output/stream/points` veröffentlicht jedes Update an seine Abonnenten. Was der Stream selbst empfängt, hängt vom Quellknoten ab:

| Data Layer | Quelle, die jedes Update veröffentlicht (zum Beispiel `control/subscribe/output/stream/result` von AI Object Matching oder `control/subscribe/output/stream/points` eines anderen Moduls) | Gewöhnlicher Knoten (zum Beispiel ein SPS-Array) |
| --- | --- | --- |
| ctrlX Data Layer (ctrlX OS) | Jedes Update, in Reihenfolge. | Der Wert etwa alle 100 ms. Änderungen dazwischen werden nicht gesehen. |
| LumiScan Keryx (PC) | Jedes Update, in Reihenfolge. | Jede **Änderung**: Dieselben Werte erneut zu schreiben ist kein Update. |

Auf dem ctrlX Data Layer wurde der Stream mit einer SPS-Quelle auf einem Gerät noch nicht gemessen.

Das Stream-Konzept aller LumiScan-Anwendungen ist unter [Streams (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) beschrieben.

# Ordnerstruktur von LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/folder-structure.html

Die Einstellungen der Anwendung sind Dateien in ihrem Einstellungsordner **lumiscan-calibration**. Er enthält:

- **lumiscan-calibration.json**, die Anwendungseinstellungen. Siehe [Anwendungs-Einstellungsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/application-settings-file.html).
- **\<module name>.json** für jedes Modul, zum Beispiel **example.json**. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).
- **\<file name>.tiff**, die Kalibrierdaten, die ein Modul benennt, bereitgestellt von HD Vision Systems. Siehe [TIFF-Datei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/tiff-file.html).
- **schemas**, die die Einstellungsdateien für den Editor beschreiben.

## Auf ctrlX OS: Bearbeiten mit der integrierten Website {#edit-with-built-in-website}

1. Melden Sie sich an der ctrlX-OS-Website an.

2. Gehen Sie zu **Home**.

3. Wählen Sie **Manage app data**.

   ![ctrlX-OS-Startseite mit Manage app data](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/2a.png)

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

   ![Listenansicht von Manage app data mit dem Menü File View](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/1a.png)

5. Öffnen Sie den Ordner **lumiscan-calibration**. Er enthält die oben aufgeführten Dateien.

6. Klicken Sie auf einen Dateinamen, um ihn im Fenster JSON Settings rechts zu öffnen.

   ![Fenster JSON Settings](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/jsonsettings.png)

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

Auf einem PC sind die Einstellungen gewöhnliche Dateien. Unter Windows ist der Einstellungsordner `%APP_RESOURCE_DIR%\etc\lumiscan-calibration`, oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`. Siehe auch [Wo die Dateien liegen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files).

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

# Anwendungs-Einstellungsdatei – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/application-settings-file.html

Die Einstellungen der Anwendung sind in **lumiscan-calibration.json** gespeichert. Enthält der Einstellungsordner keine solche Datei, kopiert die Anwendung beim Start ihr Beispiel dorthin, zusammen mit dem Beispielmodul.

- **Auf ctrlX OS:** Die Beispiel-TIFF-Datei wird nicht mit der App ausgeliefert. Das Beispielmodul meldet Status `-2`, bis Sie Ihre eigene TIFF-Datei hochladen und das Modul zurücksetzen.
- **Auf einem PC:** Die Beispiel-TIFF-Datei wird mit der Installation ausgeliefert, sodass das Beispielmodul sofort funktioniert.

```json
{
    "$schema": "schemas/lumiscan-calibration.schema.json",
    "meta": {
        "inputFileType": "LumiScan-CtrlX-Calibration",
        "inputFileVersion": "1.0.0",
        "targetMachine": "MachineName",
        "programName": "LumiScan-Calibration",
        "programVersion": "1.0.0"
    },
    "modules": [
        "example.json"
    ],
    "system": {
        "debug": false,
        "logLevel": "INFO",
        "storage": {
            "type": "Internal",
            "parameters": {
                "rootPath": "output"
            }
        }
    }
}
```

Die Parameter sind in [Tabelle 4](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/application-settings-file.html#table-4-application-settings) beschrieben. Die Datei darf Kommentare enthalten (`//` und `/* */`).

**Tabelle 1. Tabelle 4: Beschreibung der JSON-Einstellungsdatei der Anwendung**

| Parameter | Beschreibung |
| --- | --- |
| `meta` | Metadaten der Datei. Sie dienen nur der Information. |
| `meta.inputFileType` | Der Dateityp: `LumiScan-CtrlX-Calibration`. |
| `meta.inputFileVersion` | Die Version des Dateiformats: `1.0.0`. |
| `meta.targetMachine` | Der Name der Maschine, für die die Konfiguration bestimmt ist. |
| `meta.programName` | Die Anwendung, die die Datei verwendet: `LumiScan-Calibration`. |
| `meta.programVersion` | Die Anwendungsversion, für die die Konfiguration erstellt wurde. |
| `modules` | Die Modul-Konfigurationsdateien, relativ zu dieser Datei. Jede ist ein Modul, benannt nach ihrer Datei ohne `.json`. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html). |
| `system.logLevel` | Der Log-Level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` oder `OFF`. Der Standard ist `INFO`. |
| `system.debug`, `system.storage` | Gemeinsam mit den anderen LumiScan-Anwendungen. Von LumiScan Calibration nicht verwendet. |

> [!NOTE]
> Starten Sie LumiScan Calibration nach einer Änderung dieser Datei neu, zum Beispiel nach dem Hinzufügen eines Moduls.
>
> - Kann die Datei nicht gelesen werden, schreibt die Anwendung den Grund in das Protokoll und beendet sich.
> - Ein Modul, dessen Datei oder TIFF-Datei nicht geladen werden kann, wird trotzdem bedient: Es meldet Status `-2` (`invalidSetting`), bis seine Dateien korrigiert sind und das Modul zurückgesetzt wird.
> - Ohne aufgeführtes Modul läuft die Anwendung weiter, und `hdvisionsystems/lumiscan-calibration/system/status-text` meldet das.

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

Auf einem PC schreibt die Calibration ein Beispiel ihrer Einstellungen in einen Ordner Ihrer Wahl und beendet sich, ohne zu starten. Zum Beispiel unter Windows:

```shell
lumiscan-calib --generate-settings C:\work\calibration-settings
```

Ohne Ordner (`-g` allein) schreibt sie in den aktuellen Ordner. Das Beispiel besteht aus der Anwendungs-Einstellungsdatei `lumiscan-calibration.json`, ihrer Beispiel-Moduldatei `example.json` mit der Lookup-Tabelle `example.tiff`, die dieses Modul benennt, und den vier Schemata im Ordner `schemas`, mit denen ein Editor sie prüft. Vorhandene Dateien werden nie überschrieben: Liegt eine davon bereits im Ordner, wird nichts geschrieben, und die Calibration nennt welche.

Die Calibration nennt dann den Ordner, aus dem sie ihre Einstellungen liest, standardmäßig (Windows) `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`. Bearbeiten Sie das Beispiel, kopieren Sie es dorthin, und starten Sie die Calibration.

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

Alle Einstellungen dieser Datei, wie sie ihr JSON-Schema `lumiscan-calibration.schema.json` festlegt, erzeugt für Version 2.0.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.** |

## 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 Calibration 2.0.0 stehen außerdem zum Download bereit: [JSON-Schemas von LumiScan Calibration 2.0.0](https://docs.hdvisionsystems.com/schemas/lumiscan-calibration/2.0.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-calibration/2.0.0/lumiscan-calibration.schema.json",
  ...
}
```

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

# Modul-Konfigurationsdatei – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html

Jedes Modul wird in einer eigenen Datei konfiguriert, **\<module name>.json**. Der Name der Datei ohne `.json`, in Kleinbuchstaben, ist der Name des Moduls auf dem Data Layer: `hdvisionsystems/lumiscan-calibration/<module name>`. Die Anwendung bringt ein Beispiel mit, **example.json**: das Modul `example`.

Die Konfiguration legt fest, wie 2D-Bildkoordinaten in 3D-Koordinaten auf der kalibrierten Ebene umgerechnet werden, und optional einen Stream von Punkten, die umzurechnen sind.

```json
{
    "$schema": "schemas/lumiscan-calibration-module.schema.json",
    "meta": {
        "inputFileType": "LumiScan-CtrlX-Calibration-Module",
        "inputFileVersion": "1.0.0",
        "targetMachine": "MachineName",
        "programName": "LumiScan-Calibration",
        "programVersion": "1.0.0"
    },
    "transform": {
        "name": "PlanarProjectionExample",
        "type": "from2dTo3d",
        "subtype": "lookUpTable",
        "relativePathToTiff": "example.tiff",
        "interpolationMethod": "linear4Neighbors",
        "offsetX": 0.0,
        "offsetY": 0.0,
        "scaleX": 1.0,
        "scaleY": 1.0
    },
    "stream": {
        "address": "hdvisionsystems/lumiscan-ai-object-matching/example/control/subscribe/output/stream",
        "onEntry": [
            {
                "kind": "remap",
                "node": "result",
                "array": "instances",
                "x": "oriented_bounding_box.center_x",
                "y": "oriented_bounding_box.center_y"
            }
        ],
        "enable": true,
        "keepLatestOutput": true,
        "queueSize": 64
    }
}
```

Die Parameter sind in [Tabelle 5](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html#table-5-module-settings) beschrieben. Die Datei darf Kommentare enthalten (`//` und `/* */`).

Der Abschnitt `stream` des Beispiels liest die Ergebnisse des Beispielmoduls von LumiScan AI Object Matching, `example`, von Anfang an: den Knoten `result` seines Stream-Ordners und darin die Liste `instances`. Es transformiert den Mittelpunkt jeder im Bild-Stream gefundenen Box und schreibt die Punkte zusätzlich in die normale Ausgabe. Die Ergebnisse von AI Object Matching werden immer auf diese Weise gelesen, mit einem `remap`-Schritt in `onEntry`. Für ein Modul, das eine andere Quelle liest, ändern Sie den Abschnitt oder entfernen ihn: Ohne Abschnitt streamt ein Modul plain. Siehe [Einen Stream transformieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html).

**Tabelle 1. Tabelle 5: Beschreibung der JSON-Moduleinstellungen**

| Parameter | Beschreibung |
| --- | --- |
| `meta` | Metadaten der Datei. `inputFileType` und `inputFileVersion` sind erforderlich. |
| `meta.inputFileType` | Der Dateityp. Für eine Modul-Konfigurationsdatei muss der Wert `LumiScan-CtrlX-Calibration-Module` sein. |
| `meta.inputFileVersion` | Die Version des Dateiformats. Derzeit wird nur `1.0.0` unterstützt. |
| `meta.targetMachine` | Optional. Der Name der Maschine, für die die Konfiguration bestimmt ist. |
| `meta.programName` | Optional. Die Anwendung, die die Datei verwendet: `LumiScan-Calibration`. |
| `meta.programVersion` | Optional. Die Anwendungsversion, für die die Konfiguration erstellt wurde. |
| `transform` | Die Koordinatentransformation. |
| `transform.name` | Der Name der Transformation, wie das Protokoll ihn zeigt. Er ändert den Namen des Moduls auf dem Data Layer nicht. |
| `transform.type` | Der Transformationstyp. Derzeit wird nur `"from2dTo3d"` unterstützt. |
| `transform.subtype` | Der Transformations-Subtyp. Derzeit wird nur `"lookUpTable"` unterstützt. |
| `transform.relativePathToTiff` | Der Pfad der TIFF-Datei mit den Kalibrierdaten, relativ zu dieser Datei. Siehe [TIFF-Datei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/tiff-file.html). |
| `transform.interpolationMethod` | Wie ein Wert zwischen kalibrierten Punkten ermittelt wird: `"closestPixel"`, `"linear4Neighbors"` oder `"bilateralInterpolation"`. |
| `transform.offsetX`, `transform.offsetY` | Offsets, die von den Eingabekoordinaten abgezogen werden, bevor in der Tabelle nachgeschlagen wird. Der Standard ist `0.0`. |
| `transform.scaleX`, `transform.scaleY` | Faktoren, mit denen die Eingabekoordinaten nach dem Offset skaliert werden, bevor in der Tabelle nachgeschlagen wird. Der Standard ist `1.0`. |
| `stream` | Optional, experimentell. Ein Stream von Punkten, die bei ihrem Eintreffen umgerechnet werden: die Quelle und der Stream-Modus sowie in `onEntry` der Schritt, der jedes Update liest. Siehe [Einen Stream konfigurieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#configuring). |

> [!NOTE]
> Setzen Sie das Modul nach einer Änderung der Datei zurück (`control/reset`): Es liest die Datei und die TIFF-Datei erneut ein, ohne Neustart der Anwendung. Das gilt auch für den Abschnitt `stream`. Nur das Hinzufügen oder Entfernen eines Moduls erfordert einen Neustart.
>
> Kann die Datei oder ihre TIFF-Datei nicht geladen werden, wird das Modul trotzdem bedient, meldet aber Status `-2` (`invalidSetting`) und rechnet nichts um, bis ein Reset gelingt.

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

Alle Einstellungen dieser Datei, wie sie ihr JSON-Schema `lumiscan-calibration-module.schema.json` festlegt, erzeugt für Version 2.0.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.** |
| `transform` | object |   |   | **Pflichtangabe.** |
| `transform/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. |
| `transform/type` | string |   | `from2dTo3d` | **Pflichtangabe.** |
| `transform/subtype` | string |   | `lookUpTable` | **Pflichtangabe.** |
| `transform/relativePathToTiff` | string |   | nicht leer | **Pflichtangabe.** |
| `transform/interpolationMethod` | string |   | `linear4Neighbors`, `closestPixel` | **Pflichtangabe.** |
| `transform/offsetX` | number |   |   | **Pflichtangabe.** |
| `transform/offsetY` | number |   |   | **Pflichtangabe.** |
| `transform/scaleX` | number |   |   | **Pflichtangabe.** |
| `transform/scaleY` | number |   |   | **Pflichtangabe.** |

# TIFF-Datei – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/tiff-file.html

Die TIFF-Datei enthält die Kalibrierdaten, mit denen 2D-Bildkoordinaten in 3D-Koordinaten auf der kalibrierten Ebene umgerechnet werden. Sie ist für die Anwendung LumiScan Calibration erforderlich und wird von HD Vision Systems bereitgestellt.

So erhalten Sie eine TIFF-Datei:

1. Wenden Sie sich an HD Vision Systems, um eine Kalibrierplatte zu erhalten.
2. Legen Sie die Kalibrierplatte auf die Ebene, die Sie kalibrieren möchten.
3. Nehmen Sie mit der Kamera mindestens ein Bild der Kalibrierplatte auf.
4. Senden Sie die aufgenommenen Bilder an HD Vision Systems.
5. HD Vision Systems stellt Ihnen die zugehörige TIFF-Datei bereit.

# Neues Modul hinzufügen – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/adding-new-module.html

Sie können eine neue Moduldatei anlegen, indem Sie eine vorhandene duplizieren. Ein Modul kann auch über den Data Layer angelegt und aktiviert werden, siehe [Module hinzufügen und entfernen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#adding-and-removing-modules).

## Auf ctrlX OS {#adding-on-ctrlx-os}

1. Klicken Sie auf die drei Punkte rechts neben dem Dateinamen.

2. Wählen Sie **Copy**. Das Fenster zum Kopieren der Datei öffnet sich.

   ![Dateiaktionsmenü mit der Option Copy](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/rename.png)

   ![Dialog zum Kopieren der Datei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/copyexample.png)

3. Geben Sie einen neuen Dateinamen ein. Er wird zum Namen des Moduls auf dem Data Layer, ohne `.json` und in Kleinbuchstaben.
   > [!NOTE]
   > Sie können die Datei auch später umbenennen: Klicken Sie auf die drei Punkte rechts neben dem Dateinamen und wählen Sie **Rename**.

4. Klicken Sie zur Bestätigung auf **Copy**. Die neue Modul-Konfigurationsdatei wird angelegt.

5. Bearbeiten Sie die neue Datei, zum Beispiel um ihre eigene TIFF-Datei zu benennen. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).

6. Fügen Sie den Namen der neuen Datei den Anwendungseinstellungen (`lumiscan-calibration.json`) hinzu:

   a. Klicken Sie mit der linken Maustaste auf `lumiscan-calibration.json`. Das Fenster JSON Settings öffnet sich rechts.

      ![Fenster JSON Settings für lumiscan-calibration.json](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/jsonsettings1.png)

   b. Fügen Sie den Dateinamen der Liste `modules` hinzu.

      ![Detail des Felds modules](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/jsonsettingsdet.png)

7. Starten Sie LumiScan Calibration neu. Das neue Modul erscheint unter `hdvisionsystems/lumiscan-calibration/<module name>`.

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

1. Kopieren Sie eine vorhandene Moduldatei im Einstellungsordner unter einem neuen Namen. Der Name wird zum Namen des Moduls auf dem Data Layer, ohne `.json` und in Kleinbuchstaben.
2. Bearbeiten Sie die neue Datei, zum Beispiel um ihre eigene TIFF-Datei zu benennen. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).
3. Fügen Sie den Namen der neuen Datei der Liste `modules` der Anwendungseinstellungen (`lumiscan-calibration.json`) hinzu.
4. Starten Sie LumiScan Calibration neu. Das neue Modul erscheint unter `hdvisionsystems/lumiscan-calibration/<module name>`.

# Einstellungen auf dem Data Layer – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html

## Data Layer {#data-layer}

LumiScan Calibration bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-calibration` an.

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

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Calibration 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 Calibration zeigt die Einstellungen, mit denen es gestartet wurde, auf dem Data Layer, auf `hdvisionsystems/lumiscan-calibration/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-calibration/system/control/restart/execute` startet sie neu. Der Knoten `system` aller LumiScan-Anwendungen ist unter [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html) beschrieben.

Wo ein Ergebnis unten nur einen Namen hat, etwa `DL_OK` oder `DL_CREATION_FAILED`, ist es der Name auf dem ctrlX Data Layer; LumiScan Keryx meldet dasselbe Ergebnis unter eigenem Namen, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results).

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

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

- die Anwendungs-Einstellungsdatei `lumiscan-calibration.json`, so wie sie gelesen wurde;
- in ihrer Liste `modules` den Inhalt jeder Modul-Konfigurationsdatei 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 mit dem Namen `password` wird als `"***"` angezeigt.

Zum Beispiel:

```json
{
  "$schema": "schemas/lumiscan-calibration.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "example.json",
      "$schema": "schemas/lumiscan-calibration-module.schema.json",
      "transform": {
        "name": "PlanarProjectionExample",
        "relativePathToTiff": "example.tiff",
        ...
      }
    }
  ],
  "system": { ... }
}
```

Kommentare in den Dateien werden nicht angezeigt.

Der Knoten zeigt die Dateien, wie die Anwendung sie beim Start gelesen hat. Der Reset eines Moduls liest dessen Moduldatei erneut ein, und der Knoten zeigt dann diese Datei, wie sie gelesen wurde.

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

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

- Jedes Modul behält sein `"$file"`. Es muss eine der Moduldateien der Anwendung benennen: 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-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#adding-and-removing-modules).
- Ein Modul, das in `modules` weggelassen wird, ist in `lumiscan-calibration.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 erhalten. Ein neuer Schlüssel oder ein neues Listenelement kommt hinter das letzte vorhandene; ein entfernter Schlüssel geht mit seiner Zeile, einschließlich eines Kommentars in dieser Zeile. Nur ein Objekt, das sowohl Schlüssel gewonnen als auch verloren hat, oder eine Liste, die ein Element verloren hat, wird neu geschrieben, ohne die Kommentare darin. Die vorherige Datei wird daneben als `<file>.bak` aufbewahrt.
- Ein Schlüssel wie `"_comment"` ist Inhalt wie jeder andere, er wird also angezeigt und erhalten.

Die Anwendung prüft die Änderung, bevor etwas geschrieben wird: Die Anwendungs-Einstellungsdatei muss sich laden lassen, und jede geänderte Modul-Konfigurationsdatei muss ihre Lookup-Tabelle und ihren Abschnitt `stream` laden können, wie bei einem Reset. Eine Lookup-Tabelle, die nicht existiert, wird abgelehnt. Eine Änderung, die die Prüfung ablehnt oder die kein gültiges JSON ist, wird mit `DL_INVALID_VALUE` (ctrlX Data Layer) oder `Rejected` (LumiScan Keryx) beantwortet. Der Grund steht im Protokoll, und nichts wird geschrieben.

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

### Neustart erforderlich {#restart-required}

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

- `hdvisionsystems/lumiscan-calibration/system/restart-required` ist `true`;
- `hdvisionsystems/lumiscan-calibration/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`. Das schließt `reset` ein, das sonst einen Teil der neuen Einstellungen laden würde;
- ein laufender Stream stoppt.

Nur ein Neustart beendet das. Ein Reset nicht. Das Protokoll enthält die Meldung auf der Stufe Error.

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 Schreibzugriff mit `DL_CREATION_FAILED`. Davor 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-calibration/system` verwalten Module, jede unter `control/<method>/`, 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 wie eine geänderte Moduldatei. Das Modul ist noch nicht aktiv, es muss also 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, die Anwendung erfordert dann also einen Neustart (siehe [Neustart erforderlich](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#restart-required)). |
| `deactivate-module` | Nimmt `<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, die Anwendung erfordert dann also einen Neustart. |

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`, wenn sie fertig ist, mit `DL_INVALID_VALUE` (ctrlX Data Layer) oder `Rejected` (LumiScan Keryx), wenn sie abgelehnt hat, und mit `DL_CREATION_FAILED`, wenn eine Datei nicht geschrieben werden konnte. Zum Beispiel, um das Modul `conveyor` hinzuzufügen:

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

## Die Anwendung neu starten {#restarting}

`hdvisionsystems/lumiscan-calibration/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`, sobald der Neustart begonnen hat. Die Knoten der Anwendung verschwinden dann, bis sie wieder läuft: Warten Sie, bis `hdvisionsystems/lumiscan-calibration/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.

# Daten hochladen – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/uploading-data.html

Für die Nutzung von LumiScan Calibration ist eine TIFF-Kalibrierdatei erforderlich. Konfigurationsdateien können optional hochgeladen oder geändert werden, wenn Sie eigene Anwendungs- oder Moduleinstellungen verwenden möchten.

## Auf ctrlX OS {#uploading-on-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 wenn Sie auf die Ordnerstruktur der Anwendung zugreifen müssen.

![Hochladen von Daten über die ctrlX Web UI](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/ctrlx-web-ui-upload.png)

### Hochladen mit WebDAV

So laden Sie Dateien mit WebDAV hoch:

1. Gehen Sie auf die WinSCP-Website.

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** für **Encryption**.

6. Geben Sie Ihren Benutzernamen und Ihr Passwort ein.

   ![WinSCP-Downloadseite](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/WinSCP.png)

   ![WinSCP-Anmeldefenster](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/dav1.png)

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

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

9. Ziehen Sie die TIFF-Datei und bei Bedarf die Konfigurationsdateien per Drag-and-drop in den entsprechenden Anwendungsordner von LumiScan Calibration.

![WinSCP-Pfad auf solutions/webdav/appdata](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/dav3.png)

![WinSCP-Zweifensteransicht der appdata-Ordnerstruktur](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/dav2.png)

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

Auf einem PC sind dies gewöhnliche Dateien. Kopieren Sie sie in den Ordner, aus dem die Anwendung ihre Einstellungen liest. Unter Windows ist das:

- `%APP_RESOURCE_DIR%\etc\lumiscan-calibration`, wenn die Umgebungsvariable `APP_RESOURCE_DIR` gesetzt ist;
- andernfalls `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`.

Starten Sie LumiScan Calibration nach einer Änderung einer Datei neu.

# Fehlerbehebung – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html

Diese Seite nennt zuerst die allgemeinen Prüfungen, die bei jedem Problem helfen. Beginnen Sie mit ihnen. Suchen Sie dann Ihr Symptom in den folgenden Kategorien: Zu jedem Problem finden Sie die Symptome, mögliche Ursachen, eine Diagnose und die Lösung. Der letzte Abschnitt nennt, was Sie an den Support senden.

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

### Konfiguration {#general-configuration}

LumiScan Calibration verwendet:

- eine Anwendungs-Konfigurationsdatei (`lumiscan-calibration.json`), die auf
- eine oder mehrere Modul-Konfigurationsdateien (`<module name>.json`) verweist, von denen jede eine TIFF-Datei benennt.

Die Konfigurationsdateien finden Sie unter:

- **Auf ctrlX OS:** **Manage App Data > active > lumiscan-calibration**
- **Auf einem PC (Windows):** `%APP_RESOURCE_DIR%\etc\lumiscan-calibration`, oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`

Ihr Inhalt wird auch auf dem Data Layer angezeigt, auf `hdvisionsystems/lumiscan-calibration/system/settings`. Eine Moduldatei, die nicht gelesen werden konnte, erscheint dort mit einem `"$error"`, das den Grund nennt. Siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html).

Starten Sie LumiScan Calibration nach einer Änderung von `lumiscan-calibration.json` neu. Nach einer Änderung einer Modul-Konfigurationsdatei oder ihrer TIFF-Datei genügt ein Reset des Moduls (`control/reset`).

Weitere Informationen zu den Konfigurationsdateien finden Sie unter [Anwendungs-Einstellungsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/application-settings-file.html) und [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).

### Status der Anwendung und ihrer Module {#general-status}

- `hdvisionsystems/lumiscan-calibration/system/found-modules` führt die Module auf, die die Anwendung bedient. `hdvisionsystems/lumiscan-calibration/system/status-text` ist `"Initialized"`, sobald sie ihre Module bedient, oder nennt den Grund, warum sie keines bedient.
- `hdvisionsystems/lumiscan-calibration/<module name>/control/status/code` und `.../control/status/text` melden den Ausgang der letzten Funktion. Ein Fehlerstatus bleibt bis zum nächsten Request stehen. Die Bedeutung jedes Werts steht in [Statuscodes](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#status-code-values).
- Status `-5` (`restartRequired`) bedeutet, dass die Einstellungen auf dem Data Layer geändert wurden: Starten Sie die Anwendung mit `hdvisionsystems/lumiscan-calibration/system/control/restart/execute` neu. Siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#restart-required).

### Protokolle {#general-logs}

Lässt sich ein Problem mit den unten beschriebenen Prüfungen nicht lösen, sehen Sie im Protokoll nach. Jedes Modul schreibt, warum es seine Dateien nicht laden oder seinen Stream nicht starten konnte.

- **ctrlX OS:** das Systemprotokoll von ctrlX OS. Lesen Sie es 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).
- **PC:** die Ausgabe von LumiScan Calibration in seiner Konsole.

### Data Layer {#general-data-layer}

Bei Problemen mit dem Data Layer selbst siehe [Fehlerbehebung Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html).

## Module und Adressen {#modules-and-addresses}

### Problem: Ein Calibration-Modul erscheint nicht im Data Layer {#faq-module-not-in-data-layer}

**Symptome**

- Für ein Modul, das Sie konfiguriert haben, gibt es keinen Knoten `hdvisionsystems/lumiscan-calibration/<module name>`, und `hdvisionsystems/lumiscan-calibration/system/found-modules` führt es nicht auf.
- Es erscheint überhaupt kein Modul, oder die Anwendung selbst fehlt im Data Layer.

**Mögliche Ursachen**

- Die Modul-Konfigurationsdatei ist nicht unter `modules` in `lumiscan-calibration.json` aufgeführt. Ein aufgeführtes Modul erscheint auch dann, wenn seine Datei nicht geladen werden kann.
- Das Modul wird unter dem falschen Namen gesucht. Sein Name ist der Name seiner Datei ohne `.json`, in Kleinbuchstaben. Der `name` im Block `transform` des Moduls ändert ihn nicht.
- `lumiscan-calibration.json` wurde geändert, aber die Anwendung wurde nicht neu gestartet.
- `lumiscan-calibration.json` führt kein Modul auf.
- Die Anwendung hat sich beim Start beendet, zum Beispiel weil `lumiscan-calibration.json` kein gültiges JSON ist oder (ctrlX OS) weil die Lizenz fehlt.

**Diagnose**

1. Lesen Sie `hdvisionsystems/lumiscan-calibration/system/found-modules` - erwartet: der Name des Moduls.
2. Prüfen Sie `modules` in `lumiscan-calibration.json` - erwartet: Die Modul-Konfigurationsdatei ist aufgeführt.
3. Suchen Sie das Modul unter dem Namen seiner Datei ohne `.json`, in Kleinbuchstaben.
4. Lesen Sie `hdvisionsystems/lumiscan-calibration/system/status-text` - erwartet: `"Initialized"`. Andernfalls nennt er den Grund, warum die Anwendung kein Modul bedient, zum Beispiel wenn `lumiscan-calibration.json` kein Modul aufführt.
5. Fehlt die Anwendung selbst im Data Layer, lesen Sie das Protokoll (siehe [Protokolle](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#general-logs)) - es nennt den Grund, warum sich die Anwendung beim Start beendet hat.

**Lösung**

- **Wenn die Datei nicht aufgeführt ist:** Fügen Sie den Dateinamen der Liste `modules` von `lumiscan-calibration.json` hinzu, und starten Sie dann LumiScan Calibration neu. Siehe [Neues Modul hinzufügen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/adding-new-module.html).
- **Wenn Sie unter dem falschen Namen gesucht haben:** Verwenden Sie den Namen der Datei ohne `.json`, in Kleinbuchstaben: `hdvisionsystems/lumiscan-calibration/<module name>`.
- **Wenn `lumiscan-calibration.json` ohne Neustart geändert wurde:** Starten Sie LumiScan Calibration neu, zum Beispiel mit `hdvisionsystems/lumiscan-calibration/system/control/restart/execute`.
- **Wenn sich die Anwendung beim Start beendet hat:** Korrigieren Sie `lumiscan-calibration.json` so, wie es das Protokoll angibt, und starten Sie die Anwendung dann erneut. Nennt das Protokoll eine fehlende Lizenz, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html#licence).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit dem Inhalt von `system/status-text` und `system/found-modules` sowie `lumiscan-calibration.json`.

### Problem: Data-Layer-Adressen unter lumiscan-cam-calibration funktionieren nicht mehr {#faq-data-layer-name}

**Symptome**

Adressen, die mit `hdvisionsystems/lumiscan-cam-calibration/…` beginnen, funktionieren nicht mehr.

**Mögliche Ursachen**

- Ab v1.2.1 hat sich der Data-Layer-Name der Anwendung von `lumiscan-cam-calibration` in `lumiscan-calibration` geändert.

**Diagnose**

1. Prüfen Sie die Version von LumiScan Calibration - die Änderung betrifft v1.2.1 und neuer.
2. Prüfen Sie die Adressen, die Ihr Programm oder Ihre SPS verwendet - erwartet: Sie beginnen mit `hdvisionsystems/lumiscan-calibration/`.

**Lösung**

- **Wenn die Adressen noch den alten Namen verwenden:** Aktualisieren Sie alle Adressen auf `hdvisionsystems/lumiscan-calibration/…`. Siehe [Release Notes: v1.2.1](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/release-notes/v1-2-1-2025-07-01.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Adressen, die nicht funktionieren.

## Punkte transformieren {#transforming-points}

### Problem: `transform/ready` bleibt `false`, und der Status ist -2 {#faq-transform-not-ready}

**Symptome**

- `control/transform/ready` bleibt `false`.
- `control/status/code` ist `-2` (`invalidSetting`).
- `control/transform/execute` antwortet mit `DL_INVALID_OPERATION_MODE`.
- Ein laufender Stream veröffentlicht `NaN` für jeden Punkt.

**Mögliche Ursachen**

- Das Modul hat keine Lookup-Tabelle: Seine Modul-Konfigurationsdatei oder die darin benannte TIFF-Datei konnte nicht geladen werden, zum Beispiel weil die TIFF-Datei fehlt.
- Die Modul-Konfigurationsdatei hat ungültige oder fehlende Parameter, einschließlich ihres Abschnitts `stream`. Ein fehlerhafter Abschnitt `stream` ist eine fehlerhafte Moduldatei, zum Beispiel Stream-Modus ohne Quelle (`enable` auf `true` und keine `address`), ein Schritt einer anderen `kind` oder ein Schlüssel eines Schritts, der oben im Abschnitt statt in `onEntry` steht.
- Die Lizenz ist nicht verfügbar. Der Status ist dann `-4` (`missingLicense`), und das Modul führt keine Funktion aus, bis die Lizenz wieder vorhanden ist.

**Diagnose**

1. Lesen Sie `control/status/code` - `-2`: Eine Datei konnte nicht geladen werden; `-4`: Die Lizenz fehlt.
2. Lesen Sie das Protokoll (siehe [Protokolle](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#general-logs)) - es nennt den Grund, warum die Dateien nicht geladen werden konnten, und benennt einen fehlerhaften Schlüssel.
3. Prüfen Sie, ob die in `relativePathToTiff` benannte TIFF-Datei neben der Modul-Konfigurationsdatei liegt.
4. Prüfen Sie die Modul-Konfigurationsdatei auf ungültige oder fehlende Parameter, einschließlich ihres Abschnitts `stream`.

**Lösung**

- **Wenn eine Datei nicht geladen werden konnte (Status `-2`):** Korrigieren Sie die Dateien, und setzen Sie das Modul zurück. Das Modul rechnet nicht mit der alten Tabelle weiter, damit eine korrigierte Datei nie mit einer veralteten vermischt wird. Siehe [Die Einstellungen neu laden](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#reset).
  1. Korrigieren Sie die Modul-Konfigurationsdatei oder die TIFF-Datei.
  2. Setzen Sie das Modul zurück (`control/reset`). Ein Neustart ist nicht nötig.
  3. Prüfen Sie, ob `control/status/code` `0` und `control/transform/ready` `true` ist.
- **Wenn die Lizenz fehlt (Status `-4`):** Installieren Sie die Lizenz `SWL-W-XCx-CALIBRATExHDVSx-V2NN`. Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt. Siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html#licence).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Modul-Konfigurationsdatei, dem Namen ihrer TIFF-Datei und den Protokollzeilen des fehlgeschlagenen Ladens.

### Problem: Die Anwendung reagiert nicht auf einen Request {#faq-request-not-detected}

**Symptome**

Nachdem Sie `XXX/control/<function name>/request` auf `true` gesetzt haben, wechselt `XXX/control/<function name>/ready` nicht auf `false`, oder die Funktion läuft nicht. `XXX` ist `hdvisionsystems/lumiscan-calibration/<module name>`.

**Mögliche Ursachen**

- Mehr als ein Prozess schreibt den Knoten `request`. Das Verhalten ist dann undefiniert, weil die Anwendung einen Request verpassen kann.
- `request` wurde nicht auf `false` zurückgesetzt. Das Modul wartet darauf, dass `request` zurückfällt, so lange es dauert.
- Ihr Programm verwendet eine andere Data-Layer-Version als die Anwendung.

**Diagnose**

1. Prüfen Sie, welche Programme `XXX/control/<function name>/request` schreiben - erwartet: nur ein Prozess.
2. Lesen Sie, nachdem Sie `request` auf `true` gesetzt haben, `ready` - erwartet: `false` (das Modul hat den Request erkannt).
3. Lesen Sie, nachdem Sie `request` wieder auf `false` gesetzt haben, `ready` - erwartet: wieder `true`, wenn die Funktion abgeschlossen ist.
4. Prüfen Sie die Data-Layer-Version, die Ihr Programm verwendet - erwartet: dieselbe wie die der Anwendung.

**Lösung**

- **Wenn mehr als ein Prozess `request` schreibt:** Stellen Sie sicher, dass immer nur ein Prozess auf `XXX/control/<function name>/request` zugreift. Ein Programm, das sich nicht mit anderen abstimmen kann, kann stattdessen die `execute`-Methode verwenden (`XXX/control/<function name>/execute`), die einen zweiten Aufruf ablehnt, solange einer läuft.
- **Wenn `request` nicht zurückgesetzt wurde:** Setzen Sie `request` auf `false`, nachdem `ready` auf `false` gewechselt ist. Siehe [Eine Funktion ausführen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/general-concept-of-handshake.html#functionality-execution).
- **Wenn sich die Data-Layer-Versionen unterscheiden:** Verwenden Sie dieselbe Data-Layer-Version wie die Anwendung.

**Wenn das Problem weiterhin besteht**

Wenden Sie sich mit den unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an HD Vision Systems, zusammen mit der angeforderten Funktion und den Werten von `ready`, `request` und `control/status/code`.

### Problem: Die transformierten Koordinaten passen nicht zum Bild {#faq-coordinates-wrong}

**Symptome**

Die transformierten Koordinaten entsprechen nicht den erwarteten Positionen.

**Mögliche Ursachen**

- Eine Achse ist invertiert.
- Der benötigte Ursprung ist nicht korrekt definiert. Die Kalibrierung legt den anwendungsspezifischen Referenzpunkt nicht automatisch fest.
- Einheiten wie Millimeter und Pixel werden in der Anwendung und in den angebundenen Systemen gemischt.
- Die konfigurierte TIFF-Datei gehört nicht zur verwendeten Kamera und kalibrierten Ebene.
- Ein Punkt liegt außerhalb der Lookup-Tabelle. Er liefert einen Wert vom Rand der Tabelle, ohne Fehler.

**Diagnose**

1. Bewegen Sie ein Objekt in eine bekannte Richtung und beobachten Sie, wie sich die Koordinaten ändern - erwartet: Jede Koordinate ändert sich in die erwartete Richtung.
2. Prüfen Sie den Referenzpunkt - erwartet: Der Ursprung, den Ihre Anwendung benötigt, ist definiert.
3. Prüfen Sie die Einheiten der Anwendung und der angebundenen Systeme - erwartet: überall dieselben Einheiten.
4. Prüfen Sie `relativePathToTiff` in der Modul-Konfigurationsdatei - erwartet: die TIFF-Datei für die verwendete Kamera und kalibrierte Ebene.
5. Prüfen Sie die Eingabepunkte - erwartet: innerhalb des Bildes, für das die Lookup-Tabelle erstellt wurde.

**Lösung**

- **Wenn eine Achse invertiert ist:** Eine Koordinate ändert sich in die entgegengesetzte Richtung. Senden Sie die beobachtete und die erwartete Richtung an den Support (siehe [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information)).
- **Wenn der Referenzpunkt nicht definiert ist:** Definieren Sie den Ursprung, den Ihre Anwendung benötigt. Die Kalibrierung tut das nicht automatisch.
- **Wenn Einheiten gemischt werden:** Verwenden Sie in der gesamten Anwendung und in den angebundenen Systemen einheitliche Einheiten.
- **Wenn die falsche TIFF-Datei konfiguriert ist:** Konfigurieren Sie die TIFF-Datei für die verwendete Kamera und kalibrierte Ebene, und setzen Sie dann das Modul zurück (`control/reset`).
- **Wenn Punkte außerhalb der Lookup-Tabelle liegen:** Halten Sie die Punkte innerhalb des Bildes, für das die Tabelle erstellt wurde.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit einigen Eingabepunkten, den Koordinaten, die Sie erhalten, und den Koordinaten, die Sie erwarten.

## Streams (experimentell) {#streams-experimental}

### Problem: Der Stream startet nicht {#ts-stream-does-not-start}

**Symptome**

`control/subscribe/output/stream/active` bleibt `false`, nachdem `control/subscribe/execute` mit `control/subscribe/input/enable` auf `true` aufgerufen wurde.

**Mögliche Ursachen**

- `control/subscribe/input/address` ist leer, oder die Warteschlangengröße liegt nicht zwischen 1 und 4096: Der Aufruf antwortet mit `DL_INVALID_VALUE` (ctrlX Data Layer) oder `Rejected` (LumiScan Keryx).
- Die Modul-Konfigurationsdatei ist fehlerhaft (Status `-2`), zum Beispiel ein Schritt in `stream.onEntry`, den das Modul nicht kennt, oder ein Schlüssel eines Schritts, der oben im Abschnitt `stream` steht.
- Ein Remap-Pfad passt nicht zum Schema.
- Die Änderung konnte nicht in der Modul-Konfigurationsdatei gespeichert werden: Der Aufruf antwortet mit `DL_CREATION_FAILED`.
- Die Einstellungen wurden auf `system/settings` bearbeitet, und die Anwendung wartet auf einen Neustart: Der Aufruf antwortet mit `DL_RESOURCE_UNAVAILABLE`.
- Die Lizenz fehlt. Der Stream läuft nur, solange die Lizenz vorhanden ist.

**Diagnose**

1. Prüfen Sie die Antwort von `control/subscribe/execute` - erwartet: `DL_OK`.
2. Prüfen Sie `control/status/code` - `-2`: Die Modul-Konfigurationsdatei ist fehlerhaft; das Protokoll benennt den Schlüssel.
3. Prüfen Sie `setting/stream/enable` und `setting/stream/address` - sie zeigen, was das Modul anwendet.
4. Lesen Sie das Protokoll (siehe [Protokolle](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#general-logs)) - das Modul schreibt, warum der Stream nicht starten konnte, zum Beispiel ein Remap-Pfad, der nicht zum Schema passt.

**Lösung**

- **Wenn die Adresse leer ist oder die Warteschlangengröße außerhalb des Bereichs liegt:** Schreiben Sie den Ordner der Quelle auf `control/subscribe/input/address` oder eine Warteschlangengröße von 1 bis 4096 auf `control/subscribe/input/queue-size`, und rufen Sie `control/subscribe/execute` erneut auf.
- **Wenn der Abschnitt `stream` fehlerhaft ist oder ein Remap-Pfad nicht passt:** Korrigieren Sie den Abschnitt `stream` und setzen Sie das Modul zurück. Ein fehlgeschlagener Start wird nach dem Reset erneut versucht, oder nachdem der Stream-Modus mit `control/subscribe/execute` aus- und wieder eingeschaltet wurde. Siehe [Einen Stream konfigurieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#configuring).
- **Wenn der Aufruf mit `DL_CREATION_FAILED` antwortet:** Die Modul-Konfigurationsdatei konnte nicht gelesen oder geschrieben werden. Die Antwort und das Protokoll nennen den Grund. Es wurde nichts geändert.
- **Wenn der Aufruf mit `DL_RESOURCE_UNAVAILABLE` antwortet:** Starten Sie die Anwendung neu, siehe [Status der Anwendung und ihrer Module](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#general-status).
- **Wenn die Lizenz fehlt:** Siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html#licence).

Eine Quelle, die der Stream nicht abonnieren kann, hindert ihn nicht am Starten: Es wird alle 5 Sekunden erneut versucht, und der erste Fehlschlag steht im Protokoll. Siehe [Problem: Der Stream läuft, aber es kommen keine Punkte an](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#ts-stream-no-points).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Antwort von `control/subscribe/execute`, den Werten von `setting/stream/enable` und `setting/stream/address` sowie dem Abschnitt `stream` der Modul-Konfigurationsdatei.

### Problem: Der Stream läuft, aber es kommen keine Punkte an {#ts-stream-no-points}

**Symptome**

`control/subscribe/output/stream/active` ist `true`, aber auf `control/subscribe/output/stream/points` oder `control/subscribe/output/stream/plain-points` kommen keine oder ungültige Punkte an.

**Mögliche Ursachen**

- `received-updates` bleibt `0`: Die Quelle ändert sich nicht, oder `setting/stream/address` und das `node` des Schritts benennen einen anderen Knoten als beabsichtigt.
- `failed-updates` steigt: Die Updates sind nicht von der erwarteten Art.
- `invalid-points` steigt mit `points`: Die Punkte liegen außerhalb der Lookup-Tabelle, oder das Modul hat keine Tabelle (Status `-2`).
- `skipped-updates` steigt: Die Quelle aktualisiert schneller, als das Modul transformiert.

**Diagnose**

1. Prüfen Sie die Zähler unter `control/subscribe/output/stream/statistics` - erwartet: `received-updates` steigt, und `failed-updates`, `invalid-points` und `skipped-updates` bleiben bei `0`.
2. Vergleichen Sie `setting/stream/address` und das `node` des Schritts mit dem beabsichtigten Knoten - erwartet: der Knoten `node` im Ordner `address`, genau wie geschrieben, einschließlich Groß-/Kleinschreibung.
3. Lesen Sie das Protokoll (siehe [Protokolle](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#general-logs)) - es warnt vor einer Adresse, die den Knoten doppelt benennt, meldet, wenn die Quelle nicht abonniert werden konnte, und zeigt das erste fehlgeschlagene Update.

**Lösung**

- **Wenn `received-updates` bei `0` bleibt:** Sorgen Sie dafür, dass sich die Quelle ändert, oder korrigieren Sie `address` und `node`. Das Modul abonniert den Knoten `node` im Ordner `address`, genau wie geschrieben, einschließlich Groß-/Kleinschreibung. Eine Adresse, die noch mit dem Knoten endet, benennt ihn doppelt. Auf dem ctrlX Data Layer wird ein gewöhnlicher Knoten wie ein SPS-Array etwa alle 100 ms gelesen, und Änderungen dazwischen werden nicht gesehen; auf LumiScan Keryx ist das erneute Schreiben derselben Werte kein Update. Siehe [Was ein Stream empfängt](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#data-layers).
- **Wenn `failed-updates` steigt:** Senden Sie Updates der erwarteten Art. Ein Plain-Stream benötigt ein float32- oder float64-Array mit einer ganzen Anzahl von Punkten; ein Remap-Stream benötigt einen FlatBuffer des Typs, den sein `schema` benennt.
- **Wenn `invalid-points` steigt:** Halten Sie die Punkte innerhalb der Lookup-Tabelle, oder folgen Sie bei Status `-2` [Problem: `transform/ready` bleibt `false`, und der Status ist -2](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-transform-not-ready).
- **Wenn `skipped-updates` steigt:** Verringern Sie die Rate der Quelle oder die Zahl der Punkte pro Update. Bei kurzen Lastspitzen hilft eine größere Warteschlange (`control/subscribe/input/queue-size`, gespeichert als `queueSize`). Siehe [Die Warteschlange](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#queue).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Werten der Zähler unter `control/subscribe/output/stream/statistics` und dem Abschnitt `stream` der Modul-Konfigurationsdatei.

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

Besteht ein Problem weiterhin, senden Sie Folgendes 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).

- Die Version von LumiScan Calibration.
- Die Plattform: ctrlX OS und seine Version auf einer ctrlX CORE oder einem ctrlX IPC, oder einen PC mit Windows 11 oder Ubuntu 24.04 und LumiScan Keryx.
- Das Protokoll: auf ctrlX OS das Systemprotokoll von ctrlX OS (Logbuch der ctrlX-Weboberfläche oder `journalctl`), auf einem PC die Konsolenausgabe von LumiScan Calibration.
- Datum und Uhrzeit, zu denen der Fehler aufgetreten ist.
- Den Data-Layer-Status: `system/status-text`, `system/found-modules` und für das betroffene Modul `control/status/code`, `control/status/text` und das Ergebnis, mit dem ein `execute`-Aufruf antwortete.
- Die Konfiguration: `lumiscan-calibration.json` und die Modul-Konfigurationsdateien, oder den Inhalt von `hdvisionsystems/lumiscan-calibration/system/settings`, und den Namen der TIFF-Datei.

# FAQ – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/faq.html

Kurze Antworten auf häufige Fragen zu LumiScan Calibration. Jeder Eintrag verweist auf die Seite mit den Details. Probleme und Fehlermeldungen sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html) beschrieben.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-status-codes`). Um eine Fehlermeldung zu finden, durchsuchen Sie die Seite [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html) danach.

## Erste Schritte

### Was macht LumiScan Calibration? {#faq-what-does-calibration-do}

- **Antwort:** Es rechnet 2D-Bildkoordinaten in die zugehörigen 3D-Koordinaten auf einer kalibrierten Ebene um, zum Beispiel für das Bin Picking mit Robotern oder das Ablegen von Objekten. Die Umrechnung verwendet Kalibrierdaten aus einer TIFF-Datei. Die Anwendung läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC) und auf einem PC mit Windows 11 oder Ubuntu 24.04. Sie wird mit JSON-Einstellungsdateien konfiguriert und über den Data Layer gesteuert (Eingaben, Ausgaben und Status): den ctrlX Data Layer auf ctrlX OS, LumiScan Keryx auf einem PC. Ab v2.1.0 kann ein Modul auch einen Stream von Punkten transformieren, sobald sie eintreffen (experimentell).
- **Mehr:** [Beschreibung](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/description.html), [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html)

### Wie erhalte ich die TIFF-Kalibrierdatei? {#faq-get-tiff-file}

- **Antwort:** Die TIFF-Datei wird aus Kalibrierbildern erzeugt und von HD Vision Systems bereitgestellt:
  - Wenden Sie sich an HD Vision Systems, um eine Kalibrierplatte zu erhalten.
  - Legen Sie die Platte auf die Ebene, die Sie kalibrieren möchten.
  - Nehmen Sie mit der Kamera mindestens ein Bild der Platte auf.
  - Senden Sie die Bilder an HD Vision Systems; Sie erhalten die zugehörige TIFF-Datei.
- **Mehr:** [TIFF-Datei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/tiff-file.html)

### Wie lade ich die TIFF-Datei und die Konfigurationsdateien hoch? {#faq-upload-files}

- **Antwort:** Auf ctrlX OS können die meisten Daten direkt über die ctrlX Web UI hochgeladen werden. Alternativ verwenden Sie WebDAV, zum Beispiel mit WinSCP: Wählen Sie **WebDAV** als **File protocol** und **TLS/SSL** als **Encryption**, melden Sie sich an, navigieren Sie zu `/solutions/webdav/appdata` und ziehen Sie die Dateien in den Anwendungsordner von LumiScan Calibration. Auf einem PC sind die Dateien gewöhnliche Dateien: Kopieren Sie sie in den Einstellungsordner der Anwendung (unter Windows `%APP_RESOURCE_DIR%\etc\lumiscan-calibration`, oder ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`). Die TIFF-Datei ist erforderlich; Konfigurationsdateien sind optional.
- **Mehr:** [Daten hochladen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/uploading-data.html)

## Konfiguration

### Wo liegen die Konfigurationsdateien, und wie sind sie aufgebaut? {#faq-config-files}

- **Antwort:** Auf ctrlX OS öffnen Sie **Home** > **Manage app data** in der Weboberfläche von ctrlX OS, wählen **File View** und öffnen den Ordner `lumiscan-calibration`. Auf einem PC liegen sie im Einstellungsordner `lumiscan-calibration` (unter Windows in `%APP_RESOURCE_DIR%\etc`, oder ohne `APP_RESOURCE_DIR` in `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc`). Der Ordner enthält:
  - `lumiscan-calibration.json`: Anwendungseinstellungen; `modules` führt die zu ladenden Modul-Konfigurationsdateien auf.
  - `<module name>.json` (zum Beispiel `example.json`): Einstellungen eines Transformationsmoduls.
  - `<file name>.tiff`: Kalibrierdaten, bereitgestellt von HD Vision Systems.
  - `schemas`: die Schemata, die die Einstellungsdateien für einen Editor beschreiben. Starten Sie LumiScan Calibration nach einer Änderung von `lumiscan-calibration.json` neu. Nach einer Änderung einer Modul-Konfigurationsdatei oder ihrer TIFF-Datei genügt ein Reset des Moduls (`control/reset`). Die Einstellungen können auch auf dem Data Layer gelesen und geändert werden, auf `hdvisionsystems/lumiscan-calibration/system/settings`.
- **Mehr:** [Ordnerstruktur von LumiScan Calibration](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/folder-structure.html#edit-with-built-in-website), [Anwendungs-Einstellungsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/application-settings-file.html), [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html)

### Wie füge ich ein neues Transformationsmodul hinzu? {#faq-add-module}

- **Antwort:** Kopieren Sie eine vorhandene Moduldatei unter einem neuen Namen (auf ctrlX OS: drei Punkte > **Copy**, neuen Dateinamen eingeben und mit **Copy** bestätigen; auf einem PC: die Datei im Einstellungsordner kopieren). Fügen Sie dann den neuen Dateinamen der Liste `modules` in `lumiscan-calibration.json` hinzu und starten Sie die Anwendung neu. Der Name der Datei ohne `.json`, in Kleinbuchstaben, ist der Name des Moduls auf dem Data Layer: `hdvisionsystems/lumiscan-calibration/<module name>`. Der `name` im Block `transform` des Moduls ändert ihn nicht. Alternativ legen Sie das Modul über den Data Layer mit `system/control/create-module/execute` und `system/control/activate-module/execute` an und aktivieren es, und starten dann mit `system/control/restart/execute` neu.
- **Mehr:** [Neues Modul hinzufügen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/adding-new-module.html), [Module hinzufügen und entfernen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#adding-and-removing-modules)

### Welche Transformationsparameter kann ich einstellen? {#faq-module-parameters}

- **Antwort:** Im Block `transform` einer Moduldatei:
  - `type`: Nur `from2dTo3d` wird unterstützt; `subtype`: `lookUpTable`.
  - `relativePathToTiff`: Pfad zur TIFF-Kalibrierdatei, relativ zur Moduldatei.
  - `interpolationMethod`: `closestPixel`, `linear4Neighbors` oder `bilateralInterpolation`.
  - `offsetX`, `offsetY` (Standard `0.0`) und `scaleX`, `scaleY` (Standard `1.0`). Ein optionaler, experimenteller Abschnitt `stream` konfiguriert einen Stream von Punkten, die transformiert werden sollen.
- **Mehr:** [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html#table-5-module-settings)

## Betrieb

### Wie rechne ich einen 2D-Bildpunkt in einen 3D-Punkt um? {#faq-convert-point}

- **Antwort:** Mit `XXX` = `hdvisionsystems/lumiscan-calibration/<module name>`:
  - Prüfen Sie, ob `XXX/control/transform/ready` `true` ist.
  - Setzen Sie `XXX/input/x-coordinate` und `XXX/input/y-coordinate` auf die Pixelkoordinaten. Um mehrere Punkte auf einmal umzurechnen, schreiben Sie zusätzlich `XXX/input/x-coordinate-array` und `XXX/input/y-coordinate-array`; lassen Sie sie leer, um nur einen Punkt umzurechnen.
  - Setzen Sie `XXX/control/transform/request` auf `true`, warten Sie, bis `ready` `false` ist, und setzen Sie dann `request` auf `false`. Warten Sie, bis `ready` wieder `true` ist. Alternativ schreiben Sie einen beliebigen Wert auf `XXX/control/transform/execute`: Der Schreibzugriff kehrt zurück, wenn der Transform abgeschlossen ist.
  - Prüfen Sie, ob `XXX/control/status/code` `0` (`"ready"`) ist, und lesen Sie `XXX/output/x-coordinate`, `y-coordinate` und `z-coordinate` (und die Ausgabe-Arrays).
- **Mehr:** [Punkte transformieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#transform), [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#execute)

### Was bedeuten die Statuscodes? {#faq-status-codes}

- **Antwort:** `hdvisionsystems/lumiscan-calibration/<module name>/control/status/code` meldet den Ausgang der letzten Funktion: `0` `"ready"` (letzte Funktion erfolgreich), `1` `"settingUp"`, `2` `"running"`, `3` `"waitingForClient"`, `-1` `"undefinedError"`, `-2` `"invalidSetting"` (Modul-Konfigurationsdatei oder TIFF-Datei konnte nicht geladen werden), `-3` `"invalidInput"` (ein oder mehrere Eingabewerte sind ungültig), `-4` `"missingLicense"` (ctrlX OS: erforderliche Lizenz nicht verfügbar), `-5` `"restartRequired"` (Einstellungen auf dem Data Layer geändert: Anwendung neu starten), `-10001` `"inputXYSizeNotEqual"` (die Eingabe-Arrays sind unterschiedlich lang). Ein Fehlerstatus bleibt bis zum nächsten Request stehen.
- **Mehr:** [Statuscodes](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#status-code-values)

## Fehlerbehebung {#troubleshooting}

Probleme und Fehlermeldungen sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html) beschrieben:

- [Ein Calibration-Modul erscheint nicht im Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-module-not-in-data-layer)
- [Data-Layer-Adressen unter lumiscan-cam-calibration funktionieren nicht mehr](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-data-layer-name)
- [`transform/ready` bleibt `false`, und der Status ist -2](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-transform-not-ready)
- [Die Anwendung reagiert nicht auf einen Request](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-request-not-detected)
- [Die transformierten Koordinaten passen nicht zum Bild](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#faq-coordinates-wrong)
- [Der Stream startet nicht](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#ts-stream-does-not-start)
- [Der Stream läuft, aber es kommen keine Punkte an](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/how-tos/troubleshooting.html#ts-stream-no-points)

## Lizenzierung und Support

### Welche Lizenz brauche ich, und was passiert ohne? {#faq-licence}

- **Antwort:** Die ctrlX-Lizenz für LumiScan Calibration ist `SWL-W-XCx-CALIBRATExHDVSx-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 Lizenz, die verloren geht, während die Anwendung läuft, wird als Status `-4` `"missingLicense"` gemeldet, und das Modul führt keine Funktion aus, bis sie wieder vorhanden ist. Für einen PC siehe die Lizenzinformationen auf der Seite Voraussetzungen.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/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 Support? {#faq-support}

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

# v2.1.0 - noch nicht veröffentlicht – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/release-notes/v2-1-0.html

**Hinzugefügt:**

- **Execute-Methoden.** `control/transform/execute` und `control/reset/execute` führen einen Transform oder einen Reset mit einem einzigen Schreibzugriff aus und kehren zurück, wenn er abgeschlossen ist. Sie antworten mit `DL_TOO_MANY_OPERATIONS`, solange ein anderer Transform oder Reset des Moduls läuft, und mit `DL_INVALID_OPERATION_MODE` ohne Lookup-Tabelle oder Lizenz. Siehe [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/functionalities.html#execute).
- **Einen Stream transformieren (experimentell).** Ein Modul abonniert einen Data-Layer-Knoten, seine Quelle, und transformiert jedes Update davon, sobald es eintrifft: `address` im Abschnitt `stream` seiner Konfigurationsdatei benennt den Ordner, und der Schritt in der Liste `onEntry` des Abschnitts den Knoten darin. Der Knoten enthält entweder die Punkte selbst (ein Float-Array, zum Beispiel aus einer SPS) oder das Ergebnis einer anderen Anwendung, etwa die Objekte, die AI Object Matching in einem Bild-Stream findet. Der Schritt gibt an, welches: keiner oder `plain` für ein Array; `remap` für ein Ergebnis, mit der Liste darin (`array`) und dem `x` und `y` jedes Elements - oder ohne Liste, für einen Punkt pro Update. Ein Stream-Ergebnis wird innerhalb seines Ergebnisses gelesen, wie in der normalen Ausgabe der Anwendung. Die übrigen Schlüssel des Abschnitts sind die des Streams jeder LumiScan-Anwendung. Die Punkte werden auf `control/subscribe/output/stream/points` mit ihrer Lineage veröffentlicht - dem Kamerabild, auf dem ein AI-Ergebnis inferiert wurde, oder dem SPS-Knoten, aus dem sie stammen - und als einfaches `x0,y0,z0,x1,y1,z1,…`-Array auf `control/subscribe/output/stream/plain-points`, mit `NaN` für einen Punkt außerhalb der Lookup-Tabelle. `setting/settings-hash` identifiziert die Lookup-Tabelle und die Einstellungen, mit denen sie transformiert werden, und das `tag` des Moduls - sein Name, sofern `stream.tag` kein anderes angibt - kennzeichnet sie als seine eigenen. Mit `keep-latest-output` werden die Punkte jedes Updates zusätzlich in die normalen Ausgaben geschrieben. Das Transformieren auf Anfrage funktioniert weiter, während der Stream läuft. Siehe [Einen Stream transformieren (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html).
- **Was eine Quelle enthalten darf.** `hdvisionsystems/lumiscan-calibration/system/meta/subscription-schema` beschreibt es als JSON Schema: ein einfaches Array von Zahlen, ein `stream_points` oder ein `stream_detections`. Siehe [Was eine Quelle enthalten darf](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#subscription-schema).
- **Zur Laufzeit abonnieren.** `control/subscribe/execute` wendet die Eingaben unter `control/subscribe/input/…` an - Stream-Modus, Quelle, Warteschlangengröße, `keep-latest-output` -, während die Anwendung läuft, ohne Neustart; `control/unsubscribe/execute` entfernt die Quelle. Jedes Modul hat die Stream-Knoten, sodass das Hinzufügen eines Abschnitts `stream` nur einen Reset erfordert, und ein Modul ohne einen erhält einen, wenn es abonniert. Siehe [Zur Laufzeit abonnieren](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#subscribing).
- **Stream-Modus und Quelle in der Modul-Konfigurationsdatei gespeichert.** Die Methoden speichern sie im Abschnitt `stream`, bevor sie sie anwenden: Das Modul startet nach einem Neustart wieder mit beiden. Siehe [In der Modul-Konfigurationsdatei gespeichert](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/streams.html#kept).
- **Mehrere Module gleichzeitig.** Jedes in den Anwendungseinstellungen aufgeführte Modul wird für sich bedient, sodass ein Modul, das auf seinen Client wartet, nie ein anderes aufhält.
- **Einstellungen auf dem Data Layer.** `hdvisionsystems/lumiscan-calibration/system/settings` zeigt die Einstellungen, mit denen die Anwendung gestartet wurde: die Einstellungsdatei der Anwendung, jede Moduldatei eingebettet in ihre Liste `modules`, Passwörter als `***`. Das Schreiben darauf ändert die Dateien. Die Anwendung prüft die Änderung wie beim Start, speichert sie (die vorherige Datei als `.bak`) und verweigert dann jede Arbeit, bis sie neu gestartet wird: `restart-required`, Status `-5`. `hdvisionsystems/lumiscan-calibration/system/control/restart/execute` startet sie neu. Siehe [Einstellungen auf dem Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html).

**Geändert:**

- **Das Beispielmodul ist `example`, und es liest AI Object Matching.** Die Beispiel-Moduldatei ist jetzt `example.json`, das Modul ist also `hdvisionsystems/lumiscan-calibration/example`, nicht mehr `.../lumiscan-calibration-example-module`. Sein Abschnitt `stream` mit einem `remap`-Schritt liest von Anfang an die Ergebnisse des Beispielmoduls von AI Object Matching, ebenfalls `example`, und schreibt die Punkte zusätzlich in die normale Ausgabe. Ein Einstellungsordner, der seine Dateien bereits hat, behält sie. Siehe [Modul-Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/module-configuration-file.html).
- **`reset` lädt das Modul neu.** Ein Reset liest die Modul-Konfigurationsdatei und ihre TIFF-Datei erneut ein, sodass eine korrigierte Datei ohne Neustart wirksam wird. Kann sie nicht geladen werden, meldet das Modul `-2` und hat keine Lookup-Tabelle, bis ein Reset gelingt, statt mit der alten zu transformieren.
- **Ein Fehlerstatus bleibt bis zum nächsten Request stehen.** Bisher wurde er innerhalb von etwa 100 ms durch `0` ersetzt, bevor ein Client ihn lesen konnte.
- Das Interpolationsverfahren `bilateralInterpolation` wird jetzt vom Einstellungsschema akzeptiert.
- Modul-Konfigurationsdateien dürfen Kommentare enthalten, wie die Anwendungs-Einstellungsdatei.

**Fehlerbehebung:**

- **Eine fehlende TIFF-Datei bringt die Anwendung beim Start nicht mehr zum Absturz.** Das Modul wird bedient und meldet Status `-2` (`invalidSetting`), und `control/transform/ready` bleibt `false`, bis seine Dateien korrigiert sind und es zurückgesetzt wird.
- **Die Anwendung wartet nicht mehr endlos auf einen Client, der `request` nicht zurücksetzt,** wenn sie beendet werden soll, und ein in der Zwischenzeit angeforderter Reset wird ausgeführt.
- `control/reset/request` wurde nie quittiert. Ein Reset folgt jetzt dem Handshake.
- Eine ungültige Anwendungs-Einstellungsdatei wird in das Protokoll geschrieben, und die Anwendung beendet sich, statt abzustürzen.

# v 1.2.1 - 2025-07-01 – LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/release-notes/v1-2-1-2025-07-01.html

**Breaking Changes**

- Der Name von LumiScan Calibration im Data Layer war `lumiscan-cam-calibration`. Jetzt lautet er **`lumiscan-calibration`**

**Hinzugefügt**

- Bedienbarkeit: Unterstützung von internem Speicher, SD-Karte, USB-Speicher
- Funktionalität: Unterstützung der Array-Transformation

**Fehlerbehebung**

- Hohe CPU-Last beim Beenden des Programms, wenn keine Lizenz erkannt wurde, was den ctrlX CORE lahmlegt.

# LumiScan Calibration

URL: https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Kamera über einer Kalibrierplatte auf der Arbeitsebene](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/intro/step-1.svg)<br><br>**Die Arbeitsebene einmal kalibrieren.** Mit einer Kalibrierplatte; HDVS liefert eine TIFF-Datei. | ![Kamerabild mit markierter Position bei 812, 455 Pixeln](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/_images/intro/step-2.svg)<br><br>**Eine Position in Pixeln übergeben.** Zum Beispiel ein Teil, das eine LumiScan-Vision-App gefunden hat. | Beispielergebnis<br><br><br><br><br><br><br>x<br>412.6<br><br><br>y<br>118.2<br><br><br>z<br>0.0<br><br><br>Modul<br>cell-1<br><br>**3D-Koordinaten auf der Ebene erhalten.** Bereit für Greifen oder Ablegen durch den Roboter. |

LumiScan Calibration rechnet 2D-Bildkoordinaten in 3D-Koordinaten auf einer kalibrierten Ebene um, sodass im Kamerabild gefundene Positionen realen Koordinaten entsprechen. Sie kalibrieren die Ebene einmal mit einer Kalibrierplatte; danach lässt sich jede Pixelposition einer LumiScan-Vision-App umrechnen, einzeln oder als Array. Genau das brauchen Roboter zum Greifen aus der Kiste und zum Ablegen, auf ctrlX OS oder einem Windows- oder Ubuntu-PC.

Zur Lizenzierung siehe [Lizenz](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/lumiscan-calibration/requirements.html#licence). Fragen oder eine Fehlermeldung? Siehe die [FAQ](https://docs.hdvisionsystems.com/de/lumiscan-calibration-de/2.0.0/faq.html).
