Funktionen

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;
ein einziger Schreibzugriff auf ihre execute-Methode, siehe Execute-Methoden.

Ein Modul kann auch einen Stream von Punkten transformieren, sobald sie eintreffen, siehe Einen Stream transformieren (experimentell).

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.

Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzt LumiScan Calibration LumiScan Keryx.

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Calibration bietet:

ready/request-Handshakes
Execute-Methoden
ein Stream-Abonnement auf eine Quelle (experimentell)

Wie Adressen aufgebaut sind, wie Funktionen aufgerufen werden, die Statuscodes und die Werkzeuge sind in LumiScan Keryx beschrieben.

Adressen

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.
	`control/transform/request`	Beschreibbar	Fordert einen Transform an, siehe Handshake.
	`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.
	`control/reset/request`	Beschreibbar	Fordert einen Reset an, siehe Handshake.
	`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.
status	`control/status/text`	Schreibgeschützt	Derselbe Status als Text.
input	`input/x-coordinate`	Beschreibbar	Das `x` (Pixelspalte) eines Punkts.
	`input/y-coordinate`	Beschreibbar	Das `y` (Pixelzeile) eines Punkts.
	`input/x-coordinate-array`	Beschreibbar	Das `x` jedes von mehreren Punkten.
	`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/x-coordinate-array`	Schreibgeschützt	Das `x` jedes Punkts der Eingabe-Arrays, in deren Reihenfolge.
	`output/y-coordinate-array`	Schreibgeschützt	Das `y` jedes Punkts der Eingabe-Arrays.
	`output/z-coordinate-array`	Schreibgeschützt	Das `z` jedes Punkts der Eingabe-Arrays.
	`output/timestamp/seconds`	Schreibgeschützt	Wann der letzte Transform abgeschlossen wurde, in ganzen Sekunden, nach der Uhr des Geräts.
	`output/timestamp/milliseconds`	Schreibgeschützt	Die Millisekunden dieser Zeit, 0 bis 999.
	`output/timestamp/macroseconds`	Schreibgeschützt	Die Mikrosekunden dieser Zeit, 0 bis 999.
	`output/package-identifier`	Schreibgeschützt	Zählt die abgeschlossenen Transforms, beginnend bei `1`. Ein neuer Wert bedeutet neue Ausgaben.
	`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.

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.

Punkte transformieren

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.

Schreiben Sie die Eingaben.
Starten Sie den Transform mit dem Handshake oder mit control/transform/execute.
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

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

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:

Ergebnis Bedeutung Was zu tun ist

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.

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

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; -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.
-10001	`"inputXYSizeNotEqual"`	`input/x-coordinate-array` und `input/y-coordinate-array` sind unterschiedlich lang.