Listening-Point-Koordinaten: Beschränkungen und Übertragung

Dieses Dokument beschreibt das Index-Koordinatensystem, die Mindestabstandsbeschränkung sowie die Regeln zur Komprimierung und Wiederherstellung des 40×15-Index für die API-Übertragung, die erforderlich sind, wenn Sie den Listening Point (LPoint) des BATCAM FX über die API festlegen oder auf dem Bildschirm anzeigen. Jeder Code, der LPoint-Indizes verarbeitet, muss unter der Voraussetzung der in diesem Dokument beschriebenen Koordinatensystemregel (Ursprung unten rechts) geschrieben werden.

Die BF Map der vom BATCAM FX übermittelten Beamforming-Ereignisse ist in der Struktur 40x30 aufgebaut und wird bei der Übertragung als Array der Struktur 1x1200 übergeben.

Beispielbildschirm mit der auf dem RTSP-Video des BATCAM FX visualisierten BF Map. Der grüne Bereich ist der beispielhaft festgelegte Listening Point

Bild unter der Annahme, dass die BF Map auf dem RTSP-Video des BATCAM FX visualisiert wird. Der grüne Bereich ist ein Listening Point, der beispielhaft als festgelegt angenommen wird.

Die LPoint-Funktion des BATCAM FX erlaubt die Festlegung von bis zu drei Punkten; das an der festgelegten Position beamformte Audiosignal wird über die Nachricht LPointAudio (ROS-Topic /fx_{hardware_id}/lpoint_audio, Kanäle lpoint0~lpoint2) übertragen. Zur Nachrichtenstruktur siehe das Dokument zur ROS-Anbindung.

Index-Koordinatensystem

LPoint stellt ein 2D-Raster der Größe 40×30 durch einen eindimensionalen Index (0~1199) dar.

⚠️ Achtung beim Koordinatensystem: Beim BF-Map-Index des BATCAM FX liegt unten rechts 0 und oben links 1199. Da dies dem üblichen Koordinatensystem mit dem Ursprung (0) oben links entgegengesetzt ist, ist bei der Komprimierung/Wiederherstellung zwingend die Umrechnung 1199 - n erforderlich. Wenn Sie ohne diese Umrechnung direkt mit n % 40 und n / 40 rechnen, erhalten Sie falsche Ergebnisse.

Der Index beginnt unten rechts (0) und wächst nach links; ist eine Zeile (40 Zellen) abgeschlossen, rückt er eine Zeile nach oben. Wenn Sie die Rasterkoordinaten also mit x = n mod 40 und y = ⌊n / 40⌋ berechnen, wächst x von rechts nach links und y von unten nach oben. Die Indizes der vier Ecken lauten wie folgt.

Position	Index
Unten rechts	0
Unten links	39
Oben rechts	1160
Oben links	1199

Beschränkungen

Beim Festlegen von Listening Points darf der Abstand zwischen zwei Punkten nicht zu gering sein.

In der aktuellen LPoint-Einstellung des BATCAM FX ist die folgende Mindestabstandsbeschränkung festgelegt:

Horizontale Richtung: mindestens ±2 Zellen
Vertikale Richtung: mindestens ±2 Zellen

Das heißt: Sobald ein Listening Point festgelegt ist, kann der gesamte Bereich innerhalb von 2 Zellen in horizontaler und vertikaler Richtung davon nicht für einen weiteren Listening Point verwendet werden.

Nehmen Sie zum Beispiel an, dass die folgenden Listening Points festgelegt wurden (x und y unten sind die mit x = n mod 40 und y = ⌊n / 40⌋ berechneten Rasterkoordinaten — bezogen auf den Ursprung unten rechts):

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

Um diese beiden Listening Points wird der folgende Sperrbereich festgelegt:

Bezogen auf A: 18 ≤ x ≤ 22, 0 ≤ y ≤ 2 (die negative y-Richtung liegt außerhalb des Rasters und wird daher bei 0 abgeschnitten)
Bezogen auf B: 18 ≤ x ≤ 22, 12 ≤ y ≤ 16

Innerhalb dieser Bereiche dürfen keine weiteren Listening Points festgelegt werden.

Komprimierung und Wiederherstellung des LPoint-Index für die Verwendung in der API

Bei API-Anfragen müssen Sie den Index in die 40×15-Form mit auf die Hälfte reduzierter vertikaler Auflösung (Index 0~~599) umrechnen und in dieser Form übertragen. Ab Firmware v1.0.2d wurde der zulässige Bereich des lpoint-Index in der Beamforming-Einstellungs-API von 0~~1199 auf 0~599 geändert (siehe Firmware-Release-Notes).

Verwenden Sie dazu die folgenden Formeln, um die Komprimierung (Downsize) und die Wiederherstellung (Upsize) durchzuführen.

💡 Hinweis: Da die Komprimierung die vertikale Auflösung auf die Hälfte reduziert, können Informationen verloren gehen. Wenn Sie Koordinatengenauigkeit benötigen, bewahren Sie den ursprünglichen Index vor der Komprimierung separat auf. Einzelheiten zu den Verlust- und Wiederherstellungsregeln finden Sie unten im Abschnitt Grenzen und Grenzwerte.

Index-Komprimierung (Downsize)

Der eindimensionale Index n (0~1199) wird auf das 40×15-Raster umgerechnet.

Nach der Umkehrung des Koordinatensystems (1199 - n) wird die vertikale Auflösung auf die Hälfte reduziert und damit die y-Koordinate komprimiert.

Formel:

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

Beispiele:

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

Index-Wiederherstellung (Upsize)

Der komprimierte Index wird auf die ursprüngliche 40×30-Basis wiederhergestellt.

Die Wiederherstellung erfolgt auf Basis der oberen Zeile (y * 2) der bei der Komprimierung entfallenen Zeilen; anschließend wird das Koordinatensystem wieder umgekehrt.

Formel:

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

Beispiele:

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

Zusammenfassung der Einsatzfälle

Situation	Verwendete Funktion	Beschreibung
Koordinatenübertragung bei API-Anfrage	Downsize	Komprimierung 40×30 → 40×15
Koordinatenausgabe auf dem Benutzerbildschirm	Upsize	Wiederherstellung 40×15 → 40×30

Als Code in den jeweiligen Sprachen ausgedrückt ergibt sich Folgendes.

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);
}

API-Übertragungsverfahren

Den umgerechneten LPoint-Index übertragen Sie über den Parameter index_l der Beamforming-Einstellungs-API. Das BATCAM FX-Gerät stellt die API direkt bereit (Basis-URL http://{device_ip}), und für die Authentifizierung wird Basic-Authentifizierung verwendet.

Punkt	Inhalt
Einstellungen abfragen	`GET /beamforming/setting` — gibt die aktuellen Beamforming-Einstellungswerte zurück; `index_l` in der Antwort ist ein Array aus drei Ganzzahlen.
Einstellungen ändern	`PATCH /beamforming/setting` — die Übertragung erfolgt im Format `multipart/form-data`.
Anfrageformat für `index_l`	Durch Kommas getrennte Zeichenkette aus drei L points (Beispiel: `20,510,579`)
Achtung	Teilweise Einstellungen werden nicht übernommen, daher müssen Sie alle Werte übertragen. Rufen Sie zunächst mit GET die aktuellen Einstellungen ab, ändern Sie dann nur `index_l` und übertragen Sie anschließend wieder den gesamten Satz.
Fehlerantwort	Bei Übergabe eines fehlerhaften lpoint-Parameters wird eine 400-Antwort (`error: 1`, `message: lpoint parameter error`) zurückgegeben.

Bei Erfolg wird die Antwort in einer Envelope-Struktur zurückgegeben:

{
  "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]
  }
}

Das vollständige Schema von Anfrage und Antwort sowie Tests mit tatsächlichen Aufrufen finden Sie in der Gruppe beamforming des FX API Playground. Zu den Eigenschaften der einzelnen Beamforming-Einstellungswerte einschließlich index_l siehe das Dokument zu den Beamforming-Parametern.

Grenzen und Grenzwerte

Die Komprimierung der vertikalen Auflösung geht mit Informationsverlust einher. Da die bereitgestellten Komprimierungs- und Wiederherstellungsfunktionen jeweils nur die vertikale Richtung auf die Hälfte komprimieren, können zwei ursprünglich unterschiedliche Indizes auf denselben Wert abgebildet werden. Zum Beispiel werden 0 und 40 bei der Komprimierung beide zu 599, und 1159 und 1199 werden beide zu 0.

Die Wiederherstellungsfunktion stellt immer auf Basis der oberen Zeile wieder her. Beim Wiederherstellen eines komprimierten Index stellt die Wiederherstellungsfunktion auf Basis der oberen Zeile (y * 2) der beiden ursprünglich möglichen Zeilen wieder her und kehrt anschließend das Koordinatensystem erneut um (1199 - result).

Beim Anzeigen der API-Antwort oder der Ergebnisse kann die Position daher gegenüber der vom Benutzer wahrgenommenen Position leicht verschoben sein; wenn eine exakte Wiederherstellung erforderlich ist, müssen Sie die ursprünglichen Koordinateninformationen unter Umständen vor der Komprimierung separat speichern.

Zusammenfassung der Grenzwertbehandlung

Die Angabe Vollständige Wiederherstellung in der nachstehenden Tabelle gibt an, ob nach der Komprimierung (Downsize) und der anschließenden Wiederherstellung (Upsize) der ursprüngliche Eingabeindex unverändert zurückkommt. Zum Beispiel wird 0 zu 599 komprimiert und danach zu 40 wiederhergestellt, daher ❌; 40 wird zwar zum gleichen Wert 599 komprimiert, das Wiederherstellungsergebnis ist aber wieder 40, daher ✅.

Eingabewert	Komprimierungsergebnis	Wiederherstellungsergebnis	Vollständige Wiederherstellung
0	599	40	❌ (Kollision möglich)
40	599	40	✅
1159	0	1199	❌ (Kollision möglich)
1160	39	1160	✅
1199	0	1199	✅

Verallgemeinert gilt: Indizes, die im umgekehrten Koordinatensystem (1199 - n) in einer geraden y-Zeile liegen, werden vollständig wiederhergestellt.