Eine Methode ausführen

Jede Kameraoperation liegt unter derselben Adresse: hdvisionsystems/lumiscan-cam-driver/<camera name>/control/<operation>/.

Die meisten Operationen können auf zwei verschiedene Arten gestartet werden, und beide führen zum selben Ergebnis:

Schreiben Sie auf den Methodenknoten execute. Das führt die Operation einmal aus und kehrt erst zurück, wenn sie abgeschlossen ist. Es ist ein einzelner Schreibvorgang, Ihr Programm muss also keinen Zustand verfolgen.
Verwenden Sie den ready/request-Handshake. Er startet die Operation und kehrt sofort zurück; Ihr Programm beobachtet das Signal ready, um zu erfahren, wann die Operation abgeschlossen ist. Siehe Grundkonzept des Handshakes.

Der Handshake funktioniert für jede Operation außer trigger. Die Methode execute ist für die meisten, aber nicht für alle Operationen verfügbar.

Tabelle 1. Startmöglichkeiten jeder Operation
Operation	`execute`	ready/request
`capture`	Ja	Ja
`save`	Ja	Ja
`load`	Ja	Ja
`remove`	Ja	Ja
`list-images`	Ja	Ja
`connect-camera`	Nein	Ja
`disconnect-camera`	Nein	Ja
`reset`	Nein	Ja
`trigger`	Ja	Nein

Connect, Disconnect und Reset werden bewusst nicht als execute-Methoden angeboten. Sie können mehrere Sekunden dauern, weil sie die vollständige Verbindung zur Kamera auf- oder abbauen, und reset trennt die Verbindung und baut sie neu auf. Ein wartender Methodenaufruf würde meist aufgeben, bevor die Kamera den Erfolg meldet, und dann einen Fehler für eine Operation melden, die tatsächlich funktioniert hat. Verwenden Sie für diese drei bitte den ready/request-Handshake.

Software-Trigger

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/trigger/execute sendet der Kamera einen Software-Trigger, aber nur, solange die Kamera im Software-Trigger-Modus ist. In jedem anderen Modus, etwa Hardware-Trigger oder Freilauf, tut der Aufruf nichts und antwortet trotzdem mit DL_OK. Die Kamera muss verbunden sein; bis dahin antwortet der Aufruf mit DL_INVALID_OPERATION_MODE. Es gibt dafür keinen ready/request- Handshake: Ein Trigger ist sofort vorbei.

Es ist kein Capture. Das Bild geht dorthin, wohin die Aufnahme der Kamera es liefert: in den Bild-Stream, solange dieser läuft. Außerhalb eines Streams wartet das Bild in der Warteschlange der Kamera (number-of-images-in-queue), und das nächste Capture nimmt es, sofern die Moduldatei nicht clearBufferBeforeCapture setzt.

Solange der Bild-Stream läuft, wird eine Kamera ohne Software-Trigger-Modus - eine simulierte Kamera, die einen Ordner mit Bildern abspielt, oder eine Plugin-Kamera ohne TriggerSoftware - stattdessen durch ihren eigenen Trigger ausgelöst: Jeder Aufruf liefert ein Bild auf control/publish/output/stream/frame. Siehe Die Kamera triggern.

Software-Trigger-Modus bedeutet, dass der Trigger-Modus der Kamera eingeschaltet und ihre Trigger-Quelle Software ist. Der Cam Driver liest beides in der eigenen Schreibweise der Kamera, genauso wie er sie beim Verbinden setzt: zum Beispiel On oder Triggered und Software oder SoftwareTrigger. Bei einer Kamera, die ihre Werte nicht auflisten kann, gelten On und Software von GenICam.

Der Befehl, der den Trigger auslöst, ist der kameraeigene: TriggerSoftware von GenICam oder SoftwareTrigger bei einer Kamera, die ihn so nennt. Ist die Kamera im Software-Trigger-Modus, hat aber keinen der beiden Befehle oder lehnt ihn ab, wird der Status -10012 (softwareTriggerFailed).

Eine Kamera, die ihren Befehl, ihren Trigger-Modus oder ihre Trigger-Quelle oder deren Werte anders benennt, erhält ihre eigenen Namen in der Anwendungs-Einstellungsdatei. Fügen Sie unter featureMappings ein Feature-Mapping hinzu und benennen Sie es über die featureMappingId der Kamera:

"cameras": [
    { "cameraId": "camera1", "serial": "200900623", "driverId": "default", "featureMappingId": "acme" }
],
"featureMappings": [
    {
        "id": "acme",
        "features": { "TriggerSoftware": "FireTrigger" },
        "values": { "TriggerSource_Software": "SW" }
    }
]

Unter features ist der Schlüssel das allgemeine Feature (TriggerSoftware, TriggerMode, TriggerSource, …) und der Wert der Name, den die Kamera dafür verwendet. Unter values ist der Schlüssel der allgemeine Wert (TriggerSource_Software, TriggerMode_On, …) und der Wert der Eintrag der Kamera dafür. Das Schema listet die Schlüssel auf. Ein gemappter Name wird zuerst versucht. Hat die Kamera ihn nicht, protokolliert der Cam Driver eine Warnung und verwendet seine eingebauten Namen. Eine featureMappingId, die kein Mapping benennt, stoppt den Cam Driver beim Start mit einem Fehler, der sie nennt. Ein unbekannter Schlüssel macht die Einstellungsdatei unlesbar: Der Cam Driver protokolliert einen Fehler, der den Schlüssel und die gültigen Schlüssel nennt, und läuft ohne Kameras.

execute aufrufen

Um eine Operation auszuführen, schreiben Sie auf ihren execute-Knoten, zum Beispiel:

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/capture/execute

Der Schreibvorgang kehrt zurück, sobald die Operation abgeschlossen ist. Zwei Ergebnisse sind auseinanderzuhalten:

Ob die Operation überhaupt gestartet werden konnte, meldet der Schreibvorgang selbst. Ein abgelehnter Schreibvorgang wird nie in eine Warteschlange gestellt, und das Ergebnis sagt, warum. Die Tabelle verwendet die Namen des ctrlX Data Layer; LumiScan Keryx auf einem PC meldet dieselben Ergebnisse als TooManyOperations, InvalidOperationMode und ResourceUnavailable, siehe Ergebnisse eines Methodenaufrufs:

Ergebnis Bedeutung Was zu tun ist

Ergebnis	Bedeutung	Was zu tun ist
`DL_TOO_MANY_OPERATIONS`	Die Kamera ist gerade mit einer anderen Operation belegt, oder der Bild-Stream startet oder stoppt gerade.	Wiederholen Sie den Aufruf. Derselbe Schreibvorgang gelingt, sobald die laufende Operation abgeschlossen ist.
`DL_INVALID_OPERATION_MODE`	Das Signal `ready` der Operation ist `false`, die Kamera ist also in einem Zustand, in dem diese Operation nicht laufen kann - zum Beispiel `capture`, während die Kamera nicht verbunden ist.	Wiederholen Sie nicht blind; der Aufruf schlägt weiter fehl. Bringen Sie die Kamera zuerst in den erforderlichen Zustand, siehe Wann eine Operation bereit ist.
`DL_RESOURCE_UNAVAILABLE`	Die Anwendung wird beendet, oder die Einstellungen wurden auf dem Data Layer geändert und ein Neustart ist erforderlich (`status/code` `-5`).	Beim Beenden: nichts, Wiederholen hilft nicht. Neustart erforderlich: Starten Sie die Anwendung neu, siehe Einstellungen auf dem Data Layer.

DL_TOO_MANY_OPERATIONS

Die Kamera ist gerade mit einer anderen Operation belegt, oder der Bild-Stream startet oder stoppt gerade.

Wiederholen Sie den Aufruf. Derselbe Schreibvorgang gelingt, sobald die laufende Operation abgeschlossen ist.

DL_INVALID_OPERATION_MODE

Das Signal ready der Operation ist false, die Kamera ist also in einem Zustand, in dem diese Operation nicht laufen kann - zum Beispiel capture, während die Kamera nicht verbunden ist.

Wiederholen Sie nicht blind; der Aufruf schlägt weiter fehl. Bringen Sie die Kamera zuerst in den erforderlichen Zustand, siehe Wann eine Operation bereit ist.

DL_RESOURCE_UNAVAILABLE

Die Anwendung wird beendet, oder die Einstellungen wurden auf dem Data Layer geändert und ein Neustart ist erforderlich (status/code -5).

Beim Beenden: nichts, Wiederholen hilft nicht. Neustart erforderlich: Starten Sie die Anwendung neu, siehe Einstellungen auf dem Data Layer.

Ob die Operation erfolgreich war, wird auf <camera name>/control/status/code und <camera name>/control/status/text gemeldet. Ein erfolgreicher Schreibvorgang bedeutet also nur, dass die Operation ausgeführt wurde - prüfen Sie danach immer den Statuscode. Anders als der Handshake lässt capture/execute den eigenen Code eines fehlgeschlagenen Capture dort stehen; über den Handshake endet ein fehlgeschlagenes Capture bei 3. Die Bedeutung jedes Werts ist in Werte des Statuscodes aufgeführt.

Ergebnisse erscheinen in beiden Fällen auf denselben Ausgabeknoten, sodass ein aufgenommenes Bild von <camera name>/output/image gelesen werden kann, egal auf welche Art das Capture gestartet wurde.

Wann eine Operation bereit ist

execute prüft genau dasselbe Signal <operation>/ready, das der Handshake verwendet, und lehnt die Ausführung ab, solange es false ist. Das Signal ist keine Formalität - die meisten Operationen hängen von etwas ab, das zuerst geschehen muss:

Operation ready ist true, wenn

Operation	`ready` ist true, wenn
`capture`	Die Kamera ist verbunden, kein Capture-Fehler ist gespeichert und der Bild-Stream läuft nicht. Ein fehlgeschlagenes Capture (zum Beispiel ein Timeout) speichert den Fehler und hält `capture/ready` auf false, bis ein `reset` erfolgreich ist - eine Kamera, die einmal aufgenommen hat und dann fehlgeschlagen ist, lehnt also jedes spätere `capture/execute` ab. Der Bild-Stream hält `capture/ready` nur auf false, solange er läuft und solange die Kamera danach neu verbindet (etwa zwei Sekunden bei der von uns getesteten Kamera); siehe Capture, während der Stream läuft.
`save`	Ein Bild ist verfügbar, also nach einem erfolgreichen `capture` oder `load`. Direkt nach dem Start der Anwendung ist es false.
`load`, `remove`	`<camera name>/output/image-files` ist nicht leer. Führen Sie zuerst `list-images` aus, oder speichern Sie ein Bild.
`list-images`	Immer.

capture

Die Kamera ist verbunden, kein Capture-Fehler ist gespeichert und der Bild-Stream läuft nicht. Ein fehlgeschlagenes Capture (zum Beispiel ein Timeout) speichert den Fehler und hält capture/ready auf false, bis ein reset erfolgreich ist - eine Kamera, die einmal aufgenommen hat und dann fehlgeschlagen ist, lehnt also jedes spätere capture/execute ab. Der Bild-Stream hält capture/ready nur auf false, solange er läuft und solange die Kamera danach neu verbindet (etwa zwei Sekunden bei der von uns getesteten Kamera); siehe Capture, während der Stream läuft.

save

Ein Bild ist verfügbar, also nach einem erfolgreichen capture oder load. Direkt nach dem Start der Anwendung ist es false.

load, remove

<camera name>/output/image-files ist nicht leer. Führen Sie zuerst list-images aus, oder speichern Sie ein Bild.

list-images

Immer.

Da connect-camera und reset nur über den Handshake verfügbar sind, kann ein Programm, das ausschließlich execute verwendet, den Zustand, den capture benötigt, nie erreichen. Verbinden Sie (und beheben Sie einen gespeicherten Fehler) über den Handshake, und verwenden Sie dann execute für die alltäglichen Operationen.

Wird ein execute abgelehnt, lesen Sie <operation>/ready zusammen mit <camera name>/control/status/code und .../status/text. ready == false benennt die fehlende Vorbedingung, und der Statustext enthält noch die Meldung des Fehlers, der sie verursacht hat.

Welche Art Sie wählen sollten

Verwenden Sie execute, wenn Ihr Programm warten kann, bis die Operation abgeschlossen ist. Das ist die einfachere Option: ein Schreibvorgang, und die Operation ist abgeschlossen, wenn der Schreibvorgang zurückkehrt.

Verwenden Sie den ready/request-Handshake, wenn:

die Operation connect-camera, disconnect-camera oder reset ist, die keine execute-Methode anbieten,
Ihr Programm nicht blockieren darf, während die Kamera arbeitet, oder
Sie bereits ein funktionierendes Programm haben, das auf dem Handshake aufbaut. Der Handshake ist unverändert und funktioniert weiterhin, er muss also nicht umgeschrieben werden.