Listening Point : limites de coordonnées et mode de transmission

Ce document décrit le système de coordonnées d’index, la distance minimale imposée ainsi que les règles de compression et de restauration des index 40×15 destinés à la transmission via l’API, nécessaires pour configurer les Listening Point (LPoint) du BATCAM FX par l’API ou pour les afficher à l’écran. Tout code manipulant les index de LPoint doit être écrit en partant de la règle de système de coordonnées de ce document (origine en bas à droite).

La BF Map des événements de Beamforming transmis par le BATCAM FX présente une structure 40x30 et est transmise sous la forme d’un tableau de structure 1x1200.

Exemple d'écran visualisant la BF Map sur le flux RTSP du BATCAM FX. La partie verte correspond aux Listening Point définis à titre d'exemple

Photo illustrant le cas où la BF Map est visualisée sur le flux RTSP du BATCAM FX. La partie verte correspond aux Listening Point supposés définis à titre d’exemple.

La fonction LPoint du BATCAM FX permet d’en définir jusqu’à 3 ; le signal audio issu du beamforming à la position définie est transmis via le message LPointAudio (topic ROS /fx_{hardware_id}/lpoint_audio, canaux lpoint0~lpoint2). Pour la structure du message, reportez-vous au document d’intégration ROS.

Système de coordonnées d’index

Le LPoint représente une grille 2D de taille 40×30 sous la forme d’un index unidimensionnel (0~1199).

⚠️ Attention au système de coordonnées : dans les index de la BF Map du BATCAM FX, le coin inférieur droit vaut 0 et le coin supérieur gauche vaut 1199. Comme cela est inverse du système de coordonnées habituel dont l’origine (0) se situe en haut à gauche, la conversion 1199 - n est impérative lors de la compression et de la restauration. Sans cette conversion, un calcul direct par n % 40 et n / 40 produit des résultats erronés.

L’index commence en bas à droite (0) et augmente vers la gauche ; lorsqu’une ligne (40 cases) se termine, il remonte d’une ligne. Autrement dit, si l’on calcule les coordonnées de la grille par x = n mod 40 et y = ⌊n / 40⌋, x augmente de la droite vers la gauche et y du bas vers le haut. Les index des quatre coins sont les suivants.

Position	Index
En bas à droite	0
En bas à gauche	39
En haut à droite	1160
En haut à gauche	1199

Restrictions

Lors de la définition des Listening Point, la distance entre deux points ne doit pas être trop faible.

Actuellement, la configuration des LPoint du BATCAM FX impose la distance minimale suivante :

Direction horizontale : au moins ±2 cases
Direction verticale : au moins ±2 cases

Autrement dit, dès qu’un Listening Point est défini, toute la zone située à moins de 2 cases horizontalement et verticalement à partir de ce point ne peut pas être utilisée pour un autre Listening Point.

Par exemple, en supposant que les Listening Point suivants ont été définis (ci-dessous, x et y sont les coordonnées de grille calculées par x = n mod 40 et y = ⌊n / 40⌋ — origine en bas à droite) :

Listening Point A : index 20 (x=20, y=0)
Listening Point B : index 580 (x=20, y=14)

Autour de ces deux Listening Point, les zones restreintes suivantes sont définies :

Par rapport à A : 18 ≤ x ≤ 22, 0 ≤ y ≤ 2 (la direction négative de y se situant hors de la grille, elle est tronquée à 0)
Par rapport à B : 18 ≤ x ≤ 22, 12 ≤ y ≤ 16

À l’intérieur de ces plages, vous ne devez pas définir de Listening Point supplémentaire.

Compression et restauration des index LPoint pour l’utilisation dans l’API

Lors d’une requête API, l’index doit être converti au format 40×15, dont la résolution verticale est réduite de moitié (index 0~~599), puis transmis. Depuis le firmware v1.0.2d, la plage autorisée pour l’index lpoint de l’API de configuration du beamforming est passée de 0~~1199 à 0~599 (voir les notes de version du firmware).

Pour cela, la compression (Downsize) et la restauration (Upsize) s’effectuent à l’aide des formules suivantes.

💡 Remarque : la compression réduisant de moitié la résolution verticale, une perte d’information est possible. Si une précision de coordonnées est nécessaire, conservez séparément l’index d’origine avant la compression. Pour le détail des règles de perte et de restauration, reportez-vous à la section Limitations et valeurs limites ci-dessous.

Compression d’index (Downsize)

L’index unidimensionnel n (0~1199) est converti sur la base d’une grille 40×15.

Après inversion du système de coordonnées (1199 - n), la résolution verticale est réduite de moitié afin de compresser la coordonnée y.

Formule :

$f(n) = 40 \cdot \left\lfloor \frac{\left\lfloor \frac{1199 - n}{40} \right\rfloor}{2} \right\rfloor + ((1199 - n) \bmod 40)$

Exemples :

f(120) → 559
f(600) → 319
f(1160) → 39

Restauration d’index (Upsize)

L’index compressé est restauré sur la base de la grille 40×30 d’origine.

La restauration s’effectue sur la base de la ligne supérieure (y * 2) parmi les lignes disparues lors de la compression, puis le système de coordonnées est de nouveau inversé.

Formule :

$f^{-1}(n) = 1199 - \left(40 \cdot (2 \cdot \left\lfloor \frac{n}{40} \right\rfloor) + (n \bmod 40)\right)$

Exemples :

f⁻¹(559) → 120
f⁻¹(319) → 600
f⁻¹(39) → 1160

Résumé des cas d’utilisation

Situation	Fonction utilisée	Description
Transmission des coordonnées lors d’une requête API	Downsize	Compression 40×30 → 40×15
Affichage des coordonnées sur l’écran utilisateur	Upsize	Restauration 40×15 → 40×30

Exprimé sous forme de code dans chacun des langages, cela donne ce qui suit.

Swift

extension Int {
    func lPointDownSized() -> Int {
        let value = 1199 - self
        let x = value % 40
        let y = value / 40
        let downY = y / 2
        return downY * 40 + x
    }

    func lPointUpSized() -> Int {
        let x = self % 40
        let y = self / 40
        let upY = y * 2
        return 1199 - (upY * 40 + x)
    }
}

Python

def l_point_down_sized(n: int) -> int:
    value = 1199 - n
    x = value % 40
    y = value // 40
    down_y = y // 2
    return down_y * 40 + x

def l_point_up_sized(n: int) -> int:
    x = n % 40
    y = n // 40
    up_y = y * 2
    return 1199 - (up_y * 40 + x)

public static class LPointExtensions
{
    public static int LPointDownSized(this int n)
    {
        int value = 1199 - n;
        int x = value % 40;
        int y = value / 40;
        int downY = y / 2;
        return downY * 40 + x;
    }

    public static int LPointUpSized(this int n)
    {
        int x = n % 40;
        int y = n / 40;
        int upY = y * 2;
        return 1199 - (upY * 40 + x);
    }
}

C++

int lPointDownSized(int n) {
    int value = 1199 - n;
    int x = value % 40;
    int y = value / 40;
    int downY = y / 2;
    return downY * 40 + x;
}

int lPointUpSized(int n) {
    int x = n % 40;
    int y = n / 40;
    int upY = y * 2;
    return 1199 - (upY * 40 + x);
}

Mode de transmission via l’API

L’index LPoint converti est transmis via le paramètre index_l de l’API de configuration du beamforming. L’équipement BATCAM FX sert directement l’API (URL de base http://{device_ip}) et l’authentification utilise l’authentification Basic.

Élément	Contenu
Consultation de la configuration	`GET /beamforming/setting` — retourne les valeurs de configuration actuelles du beamforming ; dans la réponse, `index_l` est un tableau de 3 entiers.
Modification de la configuration	`PATCH /beamforming/setting` — la transmission s’effectue au format `multipart/form-data`.
Format de requête de `index_l`	Chaîne de 3 L point séparés par des virgules (par exemple `20,510,579`)
Attention	Les configurations partielles n’étant pas prises en compte, vous devez transmettre l’ensemble des valeurs. Récupérez d’abord la configuration actuelle avec GET, puis modifiez uniquement `index_l` et retransmettez l’ensemble.
Réponse d’erreur	En cas de transmission d’un paramètre lpoint incorrect, une réponse 400 (`error: 1`, `message: lpoint parameter error`) est retournée.

En cas de succès, la réponse est retournée sous une structure d’enveloppe :

{
  "error": 0,
  "result": {
    "autogain": true,
    "gain": 100,
    "x_cal": -0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

Le schéma complet des requêtes/réponses ainsi que les tests d’appel réels sont consultables dans le groupe beamforming du playground de l’API FX. Pour les propriétés de chaque valeur de configuration du beamforming, index_l compris, reportez-vous au document sur les paramètres de beamforming.

Limitations et valeurs limites

La compression de la résolution verticale s’accompagne d’une perte d’information. Les fonctions de compression et de restauration fournies ne compressant de moitié que la direction verticale, deux index initialement différents peuvent être associés à la même valeur. Par exemple, 0 et 40 deviennent tous deux 599 après compression, et 1159 et 1199 deviennent tous deux 0.

La fonction de restauration restaure toujours sur la base de la ligne supérieure. Lorsqu’elle restaure un index compressé, la fonction de restauration effectue la restauration sur la base de la ligne supérieure (y * 2) parmi les deux lignes qui pouvaient exister à l’origine, puis inverse de nouveau le système de coordonnées (1199 - result).

Par conséquent, lors de l’affichage d’une réponse d’API ou d’un résultat, la position peut être légèrement décalée par rapport à celle perçue par l’utilisateur ; si une restauration exacte est nécessaire, il peut être nécessaire d’enregistrer séparément les informations de coordonnées d’origine avant la compression.

Résumé du traitement des valeurs limites

Dans le tableau ci-dessous, la restauration parfaite indique si l’index d’entrée initial est retrouvé tel quel après compression (Downsize) puis restauration (Upsize). Par exemple, 0 est compressé en 599 puis restauré en 40, d’où ❌ ; 40 est compressé vers le même 599 mais le résultat de la restauration redonne 40, d’où ✅.

Valeur d’entrée	Résultat de la compression	Résultat de la restauration	Restauration parfaite
0	599	40	❌ (collision possible)
40	599	40	✅
1159	0	1199	❌ (collision possible)
1160	39	1160	✅
1199	0	1199	✅

De manière générale, les index situés sur une ligne y paire dans le système de coordonnées inversé (1199 - n) sont restaurés parfaitement.