Streams (experimentell)

Streams sind experimentell: im Cam Driver ab v2.3.0, in AI Object Matching ab v2.2.0 und in Calibration ab v2.1.0. Ihre Knoten können sich noch ändern. Prüfen Sie einen Stream mit Ihrer Kamera und Ihrem Netz, bevor Sie sich darauf verlassen.

Ein Stream verarbeitet jedes Element, das eine Quelle erzeugt, sobald es eintrifft: Kamerabilder in AI Object Matching, einem Finder oder einem Code Reader; Detektionen oder Punkte in Calibration. Es gibt keinen Request pro Element. Der Produzent sendet jedes Element, ein Konsument verarbeitet es und sendet sein Ergebnis. Produzent und Konsument arbeiten gleichzeitig; deshalb ist ein Stream schneller als ein Execute-Aufruf pro Element.

Produzenten und Konsumenten

App Rolle

Cam Driver

erzeugt Bilder auf <camera>/control/publish/output/stream/frame

AI Object Matching

konsumiert Bilder, erzeugt Detektionen auf <module>/control/subscribe/output/stream/result

Template Finder, Object Finder, Area Detector, Text Reader

konsumieren Bilder, erzeugen ihre Ergebnisse auf <module>/control/subscribe/output/stream/result

DMC, QR, Aztec und Barcode Reader

konsumieren Bilder, erzeugen Codes auf <app>/control/subscribe/output/stream/result

Calibration

konsumiert Punkte oder das Ergebnis einer anderen App, erzeugt 3D-Punkte auf <module>/control/subscribe/output/stream/points und plain-points

Ein Konsument hat eine Quelle. Um zwei Kameras zu verarbeiten, verwenden Sie zwei Module.

Der Produzent: der Cam Driver

Alle Adressen beginnen mit hdvisionsystems/lumiscan-cam-driver/<camera>/.

Adresse Typ Bedeutung

control/publish/execute

Methode

wendet die folgenden Eingaben gemeinsam an

control/publish/input/enable

bool

veröffentlicht, solange true

control/publish/input/keep-latest-output

bool

schreibt jedes Bild zusätzlich in die normale Ausgabe

control/publish/input/tag

string

das Tag auf seinen Bildern; wird in der Moduldatei gespeichert

control/publish/output/stream/frame

FlatBuffers

jedes Bild, gesendet

control/publish/output/stream/active

bool

der Stream läuft

control/publish/output/stream/statistics/…​

uint64

Zähler

Der Cam Driver triggert die Kamera nie von selbst. Ein Bild kommt, wenn die Kamera per Hardware oder per control/trigger/execute getriggert wird oder wenn ihr Trigger-Modus aus ist und sie frei läuft. Der Stream benötigt eine verbundene Kamera; connect-camera, disconnect-camera und reset stoppen einen laufenden Stream. Siehe das Handbuch des Cam Driver.

Ein Konsument

Dieselben Knoten in jedem Konsumenten, unter <module>/ (bei einem Code Reader: unter <app>/):

Adresse Typ Bedeutung

control/subscribe/execute

Methode

prüft, speichert und wendet die folgenden Eingaben an

control/subscribe/input/enable

bool

Stream-Modus

control/subscribe/input/address

string

die eine Quelle: der Stream-Ordner des Produzenten

control/subscribe/input/tag

string

das Tag auf der Ausgabe dieses Moduls; leer: die Modul-ID

control/subscribe/input/queue-size

uint32

wie viele Elemente warten dürfen

control/subscribe/input/keep-latest-output

bool

schreibt jedes Ergebnis zusätzlich in die normale Ausgabe

control/unsubscribe/execute

Methode

entfernt die Quelle, die angegeben ist durch …​

control/unsubscribe/input/address

string

…​ diese Adresse; eine andere Adresse wird abgelehnt

setting/stream/…​

schreibgeschützt

was angewendet und gespeichert ist: enable, address, tag, queue-size, keep-latest-output

control/subscribe/output/stream/active

bool

der Stream läuft

control/subscribe/output/stream/<result>

FlatBuffers

jedes Ergebnis, gesendet

control/subscribe/output/stream/statistics/…​

uint64

Zähler, alle 250 ms veröffentlicht, bei jedem Start zurückgesetzt

Die Finder und Code Reader haben außerdem control/subscribe/output/stream/last-failure: warum das letzte Element fehlgeschlagen ist.

Was die Quelle eines Konsumenten enthalten muss, steht als JSON Schema auf hdvisionsystems/<app>/system/meta/subscription-schema.

Stream starten und stoppen

Die Eingaben wirken erst bei execute. enable allein zu schreiben startet nichts.

  1. Starten Sie den Produzenten: Schreiben Sie an der Kamera control/publish/input/enable = true und rufen Sie dann control/publish/execute auf. Warten Sie, bis control/publish/output/stream/active true ist.

  2. Schreiben Sie am Konsumenten control/subscribe/input/address, zum Beispiel hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream.

  3. Schreiben Sie optional tag, queue-size und keep-latest-output.

  4. Schreiben Sie control/subscribe/input/enable = true und rufen Sie dann control/subscribe/execute auf.

  5. Warten Sie, bis control/subscribe/output/stream/active true ist. Ab dann treffen Ergebnisse ein.

  6. Zum Stoppen schreiben Sie enable = false und rufen erneut execute auf.

Gut zu wissen:

  • Der Stream-Modus ist ein Pegel, kein Befehl: Der Stream läuft, solange das angewendete enable true ist.

  • Die Eingaben sind mit den angewendeten Werten vorbelegt; ändern Sie also nur, was Sie brauchen, und rufen Sie execute auf.

  • Ein Konsument kann vor seinem Produzenten gestartet werden. Ergebnisse treffen ein, sobald Elemente eintreffen. Ein fehlgeschlagenes Abonnement wird alle 5 s erneut versucht, solange der Stream läuft.

  • Eine andere Adresse ersetzt die Quelle.

  • enable = true ohne Adresse wird abgelehnt (Rejected, ctrlX DL_INVALID_VALUE), und nichts ändert sich.

Calibration als Konsument

Auch Calibration erhält einen Stream-Ordner, und ihre Moduldatei gibt an, welchen Knoten darin sie lesen und wie sie ihn in Punkte umwandeln soll: einen onEntry-Schritt im Abschnitt stream. Um die Objekte zu lesen, die AI Object Matching findet, nennt der Schritt den Knoten result, die Liste darin und die Felder, die den Punkt bilden. Ohne einen solchen Schritt liest Calibration ihre Quelle als einfaches Zahlen-Array, wie eine SPS-Variable sie liefert. Siehe das Handbuch von Calibration.

Neuestes Ergebnis behalten

Mit eingeschaltetem keep-latest-output wird jedes Element - bzw. jedes Ergebnis - zusätzlich in die normale Ausgabe des Moduls geschrieben, so wie ein Aufruf auf Anfrage es schreiben würde, und output/package-identifier wird gezählt. Eine SPS, die die normale Ausgabe liest, sieht dann das neueste Stream-Ergebnis. Ist es ausgeschaltet, veröffentlicht der Stream nur unter …​/stream/…​, und die normale Ausgabe behält das Ergebnis des letzten Aufrufs.

Stream-Ergebnisse sind FlatBuffers-Datensätze. Für eine SPS schalten Sie keep-latest-output in dem Modul ein, dessen Ergebnis Sie benötigen, und lesen dessen einfache Ausgabeknoten. Calibration veröffentlicht außerdem plain-points: alle Punkte eines Ergebnisses in einem float32-Array x0, y0, z0, x1, …​, ohne Lineage.

Was bei einem Neustart erhalten bleibt

Was Erhalten Wie

Der Stream eines Konsumenten (enable, address, tag, queue-size, keep-latest-output)

ja

control/subscribe/execute und control/unsubscribe/execute speichern ihn im Abschnitt stream der Einstellungsdatei des Moduls, bevor sie ihn anwenden. Ein Konsument, dessen gespeichertes enable true ist, abonniert beim Start von selbst

Der Stream des Cam Driver

nein

nur sein tag wird gespeichert. Rufen Sie nach jedem Start erneut control/publish/execute mit enable = true auf

Die Kameraverbindung

nein

führen Sie nach jedem Start den Handshake connect-camera aus

Lässt sich eine Datei nicht schreiben, antwortet execute mit CreationFailed (ctrlX DL_CREATION_FAILED), und nichts ändert sich.

Der Abschnitt stream der Einstellungsdatei eines Konsumenten:

"stream": {
    "enable": false,
    "address": "hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream",
    "tag": "",
    "queueSize": 1,
    "keepLatestOutput": false,
    "onEntry": []
}

Warteschlangengröße

App Bereich Standard Wenn die Warteschlange voll ist

AI Object Matching, die Finder, die Code Reader

1 bis 64

1

ein neues Element verdrängt das älteste

Calibration

1 bis 4096

64

ein neues Element verdrängt das älteste wartende

Ein Element, das aus einer vollen Warteschlange verdrängt wird, zählt als übersprungen.

Streams und einzelne Operationen

Während ein Stream läuft, werden Operationen abgelehnt, mit denen er kollidieren würde:

  • Cam Driver: capture/ready ist false; capture/execute antwortet mit InvalidOperationMode (ctrlX DL_INVALID_OPERATION_MODE). Wiederholen Sie nicht in einer Schleife. Um während des Streamings einzelne Bilder aufzunehmen, lesen Sie …​/stream/frame der Kamera, oder schalten Sie keep-latest-output ein und lesen Sie output/image, wenn sich output/package-identifier ändert.

  • AI Object Matching: inference/ready ist false; ein Handshake-Request endet mit Status 100002.

  • Finder: Eine Methode, die aufgerufen wird, während ein Bild verarbeitet wird, wird als belegt abgelehnt.

  • Code Reader: execute und der Stream behindern sich nicht; jedes Bild wird von einem eigenen Detektor gelesen.

Wird der Stream des Cam Driver gestoppt, verbindet er die Kamera neu, damit capture wieder funktioniert; das dauert etwa zwei Sekunden. Warten Sie, bis capture/ready true ist. Wechseln Sie so selten wie möglich zwischen Stream und Capture.

Die Kette verfolgen

Jede App zählt unter …​/stream/statistics/, was sie empfängt. Der erste Zähler, der nicht steigt, zeigt, wo eine Kette stehen bleibt:

App Zähler

Cam Driver

frames, published-frames, lost-frames, incomplete-frames

AI Object Matching

received-frames, inferred-frames, skipped-frames, failed-frames, lost-frames

Finder, Code Reader

received-frames, processed-frames, skipped-frames, failed-frames, lost-frames

Calibration

received-updates, transformed-updates, skipped-updates, failed-updates, lost-updates

lost- zählt Elemente, die nie eingetroffen sind, ermittelt aus Lücken in den Sequenznummern; skipped- Elemente, die aus einer vollen Warteschlange verdrängt wurden; failed-* Elemente, die nicht verarbeitet werden konnten.

Das Ergebnis: ein Envelope mit seiner Lineage

Jedes Stream-Ergebnis ist ein Envelope: zuerst die Lineage (Herkunftskette) des Elements, dann die Nutzdaten - dasselbe Ergebnis wie die Nicht-Stream-Ausgabe der App, mit einigen Unterschieden, die im Handbuch der jeweiligen App beschrieben sind.

Die Lineage listet jedes Modul auf, das das Element durchlaufen hat. Jeder Schritt hat:

Feld Bedeutung

producer

die Data-Layer-Adresse des Moduls, zum Beispiel hdvisionsystems/lumiscan-cam-driver/camera1

tag

das Tag des Moduls, oder seine Modul-ID, wenn das Tag leer ist

run

wann der Stream des Produzenten gestartet wurde (µs seit der Epoche); ein neuer Lauf zählt wieder ab 1

sequence

die Nummer des Elements im Lauf: 1, 2, …​ ohne Lücken, eine Lücke ist also ein verlorenes Element

time_us

wann der Schritt ausgeführt wurde

settings_hash

der Hash der Einstellungen, mit denen der Schritt ausgeführt wurde, wie auf setting/settings-hash

elapsed_us

wie lange der Schritt gedauert hat

external_id

die eigene Nummer des Produzenten für das Element, zum Beispiel die Block-ID der Kamera

Die Lineage enthält höchstens 16 Schritte: den Ursprung und die neuesten. Ein geänderter settings_hash bedeutet, dass sich eine Einstellung geändert hat. Jeder Hash wird einmalig in settings-history/ im Einstellungsordner der App gespeichert, sodass sich die Einstellungen hinter einem Ergebnis nachschlagen lassen.

Um auf einem PC ein Bild durch die Kette zu verfolgen, verwenden Sie LumiScan Keryx Utilities, siehe Werkzeuge.