Zum Inhalt springen
SMI Developer Center

Overlay-Parameter: Liste und Einstellungen

Übersicht

BATCAM FX unterstützt ab Firmware-Version 1.0.3 die Funktion, Overlay-Bilder geräteseitig zu überlagern und als RTSP-Stream bereitzustellen. Wenn das Overlay aktiviert ist, wird in den über RTSP und ROS 2 übertragenen Bildern das Beamforming-Overlay angezeigt. Dieses Dokument beschreibt die Eigenschaften der für die Overlay-Überlagerung verwendeten Parameter sowie deren Konfiguration.

Diese Funktion steht nur ab Firmware 1.0.3 zur Verfügung. Wie Sie das RTSP-Originalbild und die Beamforming-Daten außerhalb des Geräts (auf dem Client) direkt zusammenführen, finden Sie im Dokument BATCAM FX Übersicht.

Voraussetzungen

  • Firmware 1.0.3 oder höher: Die aktuelle Firmware-Version können Sie der Antwort von GET /setting/status im Wert result.firmware_version entnehmen. Bei einer älteren Version führen Sie das Update anhand der Dokumente Web-Software-Update oder Shell-Software-Update durch. Die Änderungen der einzelnen Versionen finden Sie in den Firmware-Release-Notes.

  • REST-API-Zugangsdaten: Alle REST-Endpunkte erfordern eine HTTP-Basic-Authentifizierung. Auf dem BATCAM FX sind standardmäßig die beiden Konten admin und user vorkonfiguriert; ändern Sie das werkseitige Standardpasswort unbedingt vor der Verwendung.

  • ROS 2-Umgebung (bei Konfiguration über ROS 2): Informationen zum Aufbau der ROS 2-Schnittstelle des Geräts finden Sie im Dokument ROS Integration, zur Einstellung der ROS Domain ID im Dokument ROS Domain ID.

Konfigurationsschnittstellen

Die Overlay-Parameter können auf zwei Wegen konfiguriert werden: über die REST API oder über eine ROS 2 Action.

SchnittstelleMethodeName / PfadHinweise
REST APIGET / PATCH/beamforming/overlayHTTP-Basic-Authentifizierung · Anfragekörper von PATCH ist multipart/form-data · ausführliche Spezifikation siehe FX API-Referenz
ROS 2Action/fx_{hardware_id}/setting_overlayAktionstyp fx_stream_msgs/action/OverlaySetting — das Feld setting des Goal ist eine OverlaySetting-Nachricht

  • PATCH /beamforming/overlay unterstützt keine Teilaktualisierungen. Auch wenn Sie nur einzelne Werte ändern, müssen Sie alle sechs Felder als form-data senden.

  • Die ROS 2-Nachrichten- und Aktionsdefinitionen finden Sie im Dokument ROS Integration oder im Repository SMI OSS - fx-stream-msgs.

Parameter-Referenz

Die folgenden Feldnamen werden sowohl als form-data-Schlüssel der REST API als auch als Feldnamen der ROS 2-Nachricht OverlaySetting verwendet.

FeldnameTypWertebereichStepHinweise
enable_overlayBooleantrue / false—Ausgabe des Overlays · Voraussetzung für die übrigen Einstellungen
enable_source_modeBooleantrue / false—Funktioniert nur, wenn das Overlay eingeschaltet ist
number_of_sourcesInteger1 ~ 51Einheit: Anzahl der Quellen · maximal 3 empfohlen · wird im Quellenerkennungsmodus verwendet
averageInteger0 ~ 101Einheit: Anzahl der Beamforming-(BF-)Maps · bei aktiviertem Quellenerkennungsmodus nicht wirksam
thresholdFloat0 ~ 1201Schwellenwert für die BF-Visualisierung · bei aktiviertem Quellenerkennungsmodus nicht wirksam
rangeFloat0 ~ 100.1Bereich der BF-Visualisierung · bei aktiviertem Quellenerkennungsmodus nicht wirksam

Abhängigkeiten zwischen den Parametern

  • enable_overlay ist die Voraussetzung für alle Overlay-Funktionen. Ist das Overlay ausgeschaltet (false), wird kein Overlay-Bild ausgegeben und auch der Quellenerkennungsmodus funktioniert nicht.

  • Wenn Sie enable_source_mode (Quellenerkennungsmodus) einschalten, arbeitet das Gerät je nach Wert von number_of_sources im Einzel- oder Mehrquellenmodus; die Werte average, threshold und range werden dabei nicht angewendet.

  • Ist enable_source_mode ausgeschaltet, werden die Werte average, threshold und range auf die Erzeugung des Overlay-Bildes angewendet.

Parameter im Detail

Enable Overlay (Feldname: enable_overlay)

Steuert, ob das Overlay-Bild ausgegeben wird. Bei Einstellung auf true wird das Overlay in den über RTSP und ROS 2 übertragenen Bildern angezeigt.

Enable Source find mode (Feldname: enable_source_mode)

Steuert den Quellenerkennungsmodus. Der Quellenerkennungsmodus funktioniert nur, wenn das Overlay eingeschaltet ist (enable_overlay=true). Bei Einstellung auf true wird je nach Wert von number_of_sources der Einzel- oder Mehrquellenmodus aktiviert. Die einstellbare Anzahl der Quellen entnehmen Sie bitte dem nachfolgenden Abschnitt Number of sources.

Number of sources (Feldname: number_of_sources)

Legt die Anzahl der gleichzeitig zu verfolgenden Quellen fest. Wird im Quellenerkennungsmodus (enable_source_mode=true) verwendet. Es können maximal 5 Quellen angegeben werden, wir empfehlen jedoch maximal 3.

Beamforming Averaging (Feldname: average)

Legt die Anzahl der Beamforming-(BF-)Maps fest, über die gemittelt wird. Damit stellen Sie die Stärke der Mittelung ein, mit der das Rauschen im Overlay-Bild reduziert wird. Je höher der Wert, desto weicher das Ergebnis.

Bei aktiviertem Quellenerkennungsmodus (enable_source_mode) wird dieser Wert nicht angewendet.

Beamforming Threshold (Feldname: threshold)

Legt den minimalen Intensitätswert fest, ab dem im Overlay-Bild eine Quelle erkannt wird. Je höher der Wert, desto ausschließlicher werden nur stärkere Quellen angezeigt.

Bei aktiviertem Quellenerkennungsmodus (enable_source_mode) wird dieser Wert nicht angewendet.

Beamforming Image Range (Feldname: range)

Legt die Bildgröße für eine Quelle im Overlay-Bild fest. Je höher der Wert, desto größer wird das Overlay für die Quelle.

Bei aktiviertem Quellenerkennungsmodus (enable_source_mode) wird dieser Wert nicht angewendet.

Konfigurationsbeispiele

REST API (curl)

Fragt die aktuelle Overlay-Konfiguration ab. Passen Sie die Geräte-IP (192.168.0.30) und die Zugangsdaten an Ihre Einsatzumgebung an.

Terminal-Fenster
curl -u 'admin:<password>' http://192.168.0.30/beamforming/overlay

Erwartete Antwort — alle Antworten verwenden dieselbe Hüllstruktur; bei error gleich 0 war die Anfrage erfolgreich.

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 1,
    "threshold": 15.0,
    "range": 5.0
  }
}

Ändert die Konfiguration. Da Teilaktualisierungen nicht unterstützt werden, senden Sie ausgehend vom obigen Abfrageergebnis alle sechs Felder als form-data.

Terminal-Fenster
curl -u 'admin:<password>' -X PATCH http://192.168.0.30/beamforming/overlay \
  -F 'enable_overlay=true' \
  -F 'enable_source_mode=true' \
  -F 'number_of_sources=3' \
  -F 'average=3' \
  -F 'threshold=30' \
  -F 'range=5'

Erwartete Antwort — die vollständige übernommene Konfiguration wird zurückgegeben.

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 3,
    "threshold": 30.0,
    "range": 5.0
  }
}

Die vollständige Spezifikation der Anfrage-/Antwortschemata finden Sie in der FX API-Referenz unter dem Eintrag /beamforming/overlay.

ROS 2 (CLI)

In einer ROS 2-Umgebung können Sie dieselbe Konfiguration über die Action /fx_{hardware_id}/setting_overlay senden.

Terminal-Fenster
ros2 action send_goal /fx_276730383020104/setting_overlay fx_stream_msgs/action/OverlaySetting \
"{
  setting: {
    enable_overlay: true,
    enable_source_mode: true,
    number_of_sources: 3,
    range: 5.0,
    threshold: 15.0,
    average: 1
  }
}"

fx_276730383020104 ist eine Beispiel-Hardware-ID. Die tatsächliche Hardware-ID können Sie der Antwort von GET /setting/status im Wert result.hardware_id entnehmen. Ausführliche Informationen zur Konfiguration über eine ROS 2 Action finden Sie im Dokument ROS-Firmware BF/Overlay-Konfiguration (Beta).

Übernahme des Ergebnisses prüfen

  • RTSP: Öffnen Sie den Videostream des Geräts mit Ihrem RTSP-Client und prüfen Sie, ob das Overlay angezeigt wird.

  • ROS 2: Das Overlay können Sie in den Bildern prüfen, die über das Topic /fx_{hardware_id}/image (sensor_msgs/msg/CompressedImage) publiziert werden.

  • Konfigurationswerte: Fragen Sie die aktuell übernommenen Werte mit GET /beamforming/overlay erneut ab und prüfen Sie die Änderungen.

Fehlerbehebung (Troubleshooting)

  • Das Overlay wird nicht im Stream angezeigt:

    • Prüfen Sie mit GET /beamforming/overlay, ob enable_overlay auf true steht.

    • Bei einer Firmware älter als 1.0.3 steht diese Funktion nicht zur Verfügung. Prüfen Sie die Version anhand von GET /setting/status im Wert result.firmware_version und aktualisieren Sie die Firmware bei Bedarf.

  • Änderungen an average / threshold / range werden nicht übernommen: Wenn enable_source_mode auf true steht, werden diese drei Werte nicht angewendet. Prüfen Sie es bei ausgeschaltetem Quellenerkennungsmodus erneut.

  • Der Quellenerkennungsmodus funktioniert nicht: Der Quellenerkennungsmodus funktioniert nur, wenn das Overlay eingeschaltet ist. Prüfen Sie, ob enable_overlay auf true steht.

  • Die PATCH-Anfrage schlägt mit 400 (error: 1) fehl: Teilaktualisierungen werden nicht unterstützt. Prüfen Sie, ob Sie alle sechs Felder als form-data gesendet haben und ob jeder Wert im zulässigen Bereich liegt.

  • Es wird 401 zurückgegeben: Die Anmeldedaten für die HTTP-Basic-Authentifizierung fehlen oder sind nicht korrekt. Prüfen Sie die Kontodaten.

Verwandte Dokumente