Aller au contenu
SMI Developer Center

Liste des paramètres Overlay et description de la configuration

Présentation

À partir de la version de firmware 1.0.3, le BATCAM FX prend en charge une fonction permettant à l’appareil lui-même de composer l’image d’overlay et de la fournir sous forme de flux RTSP. Lorsque l’overlay est activé, l’overlay de beamforming s’affiche sur les images transmises via RTSP et ROS 2. Ce document présente les propriétés des paramètres utilisés pour la composition de l’overlay ainsi que la méthode de configuration.

Cette fonction n’est disponible qu’à partir du firmware 1.0.3. Pour la méthode de composition directe du flux vidéo RTSP d’origine et des données de beamforming à l’extérieur de l’appareil (côté client), reportez-vous au document Présentation du BATCAM FX.

Prérequis

  • Firmware 1.0.3 ou ultérieur : la version de firmware actuelle peut être vérifiée dans la réponse GET /setting/status, à l’aide de la valeur result.firmware_version. Si la version est antérieure, reportez-vous au document Mise à jour logicielle via le web ou Mise à jour logicielle via le shell pour effectuer la mise à jour. Les modifications apportées à chaque version sont consultables dans les Notes de version du firmware.

  • Informations d’authentification de l’API REST : tous les points de terminaison REST requièrent une authentification HTTP Basic. Le BATCAM FX est préconfiguré avec deux comptes, admin et user ; veillez impérativement à modifier le mot de passe usine par défaut avant utilisation.

  • Environnement ROS 2 (en cas de configuration via ROS 2) : pour la configuration de l’interface ROS 2 de l’appareil, reportez-vous au document ROS Integration et, pour le réglage du ROS Domain ID, au document ROS Domain ID.

Interfaces de configuration

Les paramètres d’overlay peuvent être configurés de deux manières : via l’API REST ou via une Action ROS 2.

InterfaceMéthodeNom / cheminRemarques
REST APIGET / PATCH/beamforming/overlayAuthentification HTTP Basic · le corps de la requête PATCH est au format multipart/form-data · pour la spécification détaillée, voir la Référence de l’API FX
ROS 2Action/fx_{hardware_id}/setting_overlayType d’action fx_stream_msgs/action/OverlaySetting — le champ setting du Goal est un message OverlaySetting

  • PATCH /beamforming/overlay ne prend pas en charge les mises à jour partielles. Même lorsque seules certaines valeurs sont modifiées, les six champs doivent tous être envoyés en form-data.

  • Les définitions des messages et des actions ROS 2 sont consultables dans le document ROS Integration ou dans le dépôt SMI OSS - fx-stream-msgs.

Référence des paramètres

Les noms de champs ci-dessous sont communs aux clés form-data de l’API REST et aux noms de champs du message ROS 2 OverlaySetting.

Nom du champTypePlageStepRemarques
enable_overlayBooleantrue / false—Activation ou non de la sortie de l’overlay · condition préalable aux autres réglages
enable_source_modeBooleantrue / false—Fonctionne uniquement si l’overlay est activé
number_of_sourcesInteger1 ~ 51Unité : nombre de sources · 3 au maximum recommandé · utilisé en mode de détection de source
averageInteger0 ~ 101Unité : nombre de cartes de beamforming (BF) · non appliqué lorsque le mode de détection de source est activé
thresholdFloat0 ~ 1201Valeur de référence de la visualisation BF · non appliqué lorsque le mode de détection de source est activé
rangeFloat0 ~ 100.1Plage de la visualisation BF · non appliqué lorsque le mode de détection de source est activé

Relations de dépendance entre les paramètres

  • enable_overlay est la condition préalable à tout fonctionnement de l’overlay. Si l’overlay est désactivé (false), aucune image d’overlay n’est produite et le mode de détection de source ne fonctionne pas non plus.

  • Lorsque enable_source_mode (mode de détection de source) est activé, le système fonctionne en mode source unique ou multi-sources selon la valeur de number_of_sources ; dans ce cas, les valeurs average, threshold et range ne sont pas appliquées.

  • Si enable_source_mode est désactivé, les valeurs average, threshold et range sont appliquées à la génération de l’image d’overlay.

Détail des paramètres

Enable Overlay (nom du champ : enable_overlay)

Contrôle l’activation ou non de la sortie de l’image d’overlay. Lorsque ce paramètre est réglé sur true, l’overlay s’affiche sur les images transmises via RTSP et ROS 2.

Enable Source find mode (nom du champ : enable_source_mode)

Contrôle le mode de détection de source. Le mode de détection de source ne fonctionne que si l’overlay est activé (enable_overlay=true). Lorsque ce paramètre est réglé sur true, le mode source unique ou multi-sources est activé selon la valeur de number_of_sources. Pour le nombre de sources configurable, veuillez vous reporter à la rubrique Number of sources ci-dessous.

Number of sources (nom du champ : number_of_sources)

Définit le nombre de sources à suivre simultanément. Ce paramètre est utilisé en mode de détection de source (enable_source_mode=true). Il est possible de définir jusqu’à 5 sources, mais nous recommandons de ne pas dépasser 3.

Beamforming Averaging (nom du champ : average)

Définit le nombre de cartes de beamforming (BF) auxquelles la moyenne est appliquée. Règle l’intensité du moyennage appliqué afin de réduire le bruit de l’image d’overlay. Plus la valeur est élevée, plus le résultat est lissé.

Ce paramètre n’est pas appliqué lorsque le mode de détection de source (enable_source_mode) est activé.

Beamforming Threshold (nom du champ : threshold)

Définit l’intensité minimale à partir de laquelle un élément est considéré comme une source dans l’image d’overlay. Plus la valeur est élevée, plus seules les sources fortes sont affichées.

Ce paramètre n’est pas appliqué lorsque le mode de détection de source (enable_source_mode) est activé.

Beamforming Image Range (nom du champ : range)

Définit la taille de l’image correspondant à la source dans l’image d’overlay. Plus la valeur est élevée, plus l’overlay de la source est grand.

Ce paramètre n’est pas appliqué lorsque le mode de détection de source (enable_source_mode) est activé.

Exemples de configuration

REST API (curl)

Consultez la configuration d’overlay actuelle. Modifiez l’adresse IP de l’appareil (192.168.0.30) et les informations de compte en fonction de votre environnement d’utilisation.

Fenêtre de terminal
curl -u 'admin:<password>' http://192.168.0.30/beamforming/overlay

Réponse attendue — toutes les réponses utilisent une structure d’enveloppe commune ; la requête est réussie lorsque error vaut 0.

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

Modifiez la configuration. Les mises à jour partielles n’étant pas prises en charge, envoyez les six champs dans leur intégralité en form-data, en vous basant sur le résultat de la consultation ci-dessus.

Fenêtre de terminal
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'

Réponse attendue — l’intégralité de la configuration appliquée est renvoyée.

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

Pour la spécification complète des schémas de requête/réponse, reportez-vous, dans la Référence de l’API FX, à la rubrique /beamforming/overlay.

ROS 2 (CLI)

Dans un environnement ROS 2, la même configuration peut être envoyée au moyen de l’action /fx_{hardware_id}/setting_overlay.

Fenêtre de terminal
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 est un identifiant matériel donné à titre d’exemple. L’identifiant matériel réel peut être vérifié dans la réponse GET /setting/status, à l’aide de la valeur result.hardware_id. Pour plus de détails sur la configuration au moyen d’une Action ROS 2, reportez-vous au document Configuration BF/Overlay du firmware ROS (bêta).

Vérification du résultat appliqué

  • RTSP : ouvrez le flux vidéo de l’appareil avec le client RTSP que vous utilisez et vérifiez si l’overlay s’affiche.

  • ROS 2 : l’overlay peut être vérifié sur les images publiées sur le topic /fx_{hardware_id}/image (sensor_msgs/msg/CompressedImage).

  • Valeurs de configuration : consultez de nouveau les valeurs actuellement appliquées avec GET /beamforming/overlay afin de vérifier les modifications.

Résolution des problèmes (Troubleshooting)

  • Si l’overlay ne s’affiche pas dans le flux :

    • Vérifiez avec GET /beamforming/overlay que enable_overlay vaut true.

    • Si le firmware est antérieur à 1.0.3, cette fonction n’est pas disponible. Vérifiez la version dans GET /setting/status, à l’aide de result.firmware_version, et, si nécessaire, mettez à jour le firmware.

  • Si les modifications de average / threshold / range ne sont pas prises en compte : si enable_source_mode vaut true, ces trois valeurs ne sont pas appliquées. Vérifiez de nouveau après avoir désactivé le mode de détection de source.

  • Si le mode de détection de source ne fonctionne pas : le mode de détection de source ne fonctionne que si l’overlay est activé. Vérifiez que enable_overlay vaut true.

  • Si la requête PATCH échoue avec un code 400 (error: 1) : les mises à jour partielles ne sont pas prises en charge. Vérifiez que les six champs ont bien tous été envoyés en form-data et que chaque valeur se situe dans la plage autorisée.

  • Si un code 401 est renvoyé : les identifiants d’authentification HTTP Basic sont manquants ou incorrects. Vérifiez les informations de compte.

Documents connexes