跳转到内容
SMI Developer Center

Listening Point 坐标限制与传输方式

本文档说明通过 API 设置 BATCAM FX 的 Listening Point（LPoint）或将其显示在画面上时所需的索引坐标系、最小距离限制以及 API 传输用 40×15 索引压缩与还原规则。所有处理 LPoint 索引的代码都必须以本文档的坐标系规则（原点位于右下角）为前提编写。

BATCAM FX 传输的 Beamforming 事件中的 BF Map 由 40x30 的结构组成，传输时以 1x1200 结构的 Array 传递。

在 BATCAM FX RTSP 视频上可视化 BF Map 的示例画面。绿色部分为作为示例设置的 Listening Point

假设在 BATCAM FX RTSP 视频上可视化 BF Map 的情形所拍摄的图片。绿色部分为假设作为示例设置的 Listening Point。

BATCAM FX 的 LPoint 功能最多可指定 3 个，在所指定位置经过波束成形的音频信号将通过 LPointAudio 消息（ROS 主题 /fx_{hardware_id}/lpoint_audio，通道 lpoint0~lpoint2）传输。消息结构请参阅 ROS 集成文档。

索引坐标系

LPoint 将 40×30 大小的二维网格用一维索引（0~1199）表示。

⚠️ 坐标系注意事项：BATCAM FX 的 BF Map 索引为右下角是 0，左上角是 1199。这与一般以左上角为原点（0）的坐标系相反，因此在压缩/还原时必须进行 1199 - n 转换。若不进行该转换而直接以 n % 40、n / 40 计算，将得到错误的结果。

索引从右下角（0）开始向左递增，一行（40 格）结束后上移一行。也就是说，若按 x = n mod 40、y = ⌊n / 40⌋ 计算网格坐标，则 x 从右向左递增，y 从下向上递增。四个角的索引如下。

位置索引
右下角0
左下角39
右上角1160
左上角1199

限制事项

设置 Listening Point 时，两点之间的距离不能过近。

目前 BATCAM FX 的 LPoint 设置中规定了如下最小距离限制：

  • 水平方向：至少 ±2 格以上

  • 垂直方向：至少 ±2 格以上

也就是说，一旦指定了一个 Listening Point，其水平和垂直方向 2 格以内的所有区域都不能用作其他 Listening Point。

例如，假设指定了如下 Listening Point（以下 x、y 为按 x = n mod 40、y = ⌊n / 40⌋ 计算的网格坐标 —— 以右下角为原点）：

  • Listening Point A：索引 20（x=20, y=0）

  • Listening Point B：索引 580（x=20, y=14）

在这两个 Listening Point 周围将设置如下限制区域：

  • 以 A 为基准：18 ≤ x ≤ 22, 0 ≤ y ≤ 2（y 的负方向已超出网格，因此在 0 处截断）

  • 以 B 为基准：18 ≤ x ≤ 22, 12 ≤ y ≤ 16

在此范围内不得设置其他 Listening Point。

用于 API 的 LPoint 索引压缩与还原

发送 API 请求时，必须将索引转换为垂直方向分辨率减半的 40×15 形式（索引 0599）后再传输。自固件 v1.0.2d 起，波束成形设置 API 的 lpoint 索引允许范围已从 01199 变更为 0~599（参阅固件发布说明）。

为此，使用以下公式执行压缩（Downsize）与还原（Upsize）。

💡 参考：压缩会将垂直分辨率减半，因此可能丢失信息。若需要坐标精度，请在压缩前另行保存原始索引。有关丢失与还原规则的详细内容，请参阅下方的限制与边界值章节。

索引压缩（Downsize）

将一维索引 n（0~1199）转换为以 40×15 网格为基准的索引。

先反转坐标系（1199 - n），再将垂直分辨率减半以压缩 y 坐标。

公式：

f(n)=40⋅⌊⌊1199−n40⌋2⌋+((1199−n) mod 40)f(n) = 40 \cdot \left\lfloor \frac{\left\lfloor \frac{1199 - n}{40} \right\rfloor}{2} \right\rfloor + ((1199 - n) \bmod 40)

示例：

  • f(120) → 559

  • f(600) → 319

  • f(1160) → 39

索引还原（Upsize）

将压缩后的索引还原为原来的 40×30 基准。

以压缩时消失的两行中的上方一行（y * 2）为基准进行还原，然后再次反转坐标系。

公式：

f−1(n)=1199−(40⋅(2⋅⌊n40⌋)+(n mod 40))f^{-1}(n) = 1199 - \left(40 \cdot (2 \cdot \left\lfloor \frac{n}{40} \right\rfloor) + (n \bmod 40)\right)

示例：

  • f⁻¹(559) → 120

  • f⁻¹(319) → 600

  • f⁻¹(39) → 1160

使用场景摘要

情形使用的函数说明
API 请求时传输坐标Downsize40×30 → 40×15 压缩
在用户画面上输出坐标Upsize40×15 → 40×30 还原

将其表示为各语言对应的代码如下。

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)

C#

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 传输方式

转换后的 LPoint 索引通过波束成形设置 API 的 index_l 参数传输。BATCAM FX 设备直接提供该 API（基础 URL 为 http://{device_ip}），认证采用 Basic 认证。

项目内容
查询设置GET /beamforming/setting —— 返回当前的波束成形设置值，响应中的 index_l 是由 3 个整数组成的数组。
变更设置PATCH /beamforming/setting —— 以 multipart/form-data 格式传输。
index_l 请求格式以逗号分隔的 3 个 L point 字符串（例如 20,510,579）
注意部分设置不会被应用，因此必须传输全部值。请先通过 GET 获取当前设置，然后仅修改 index_l 并重新传输全部内容。
错误响应传入错误的 lpoint 参数时，将返回 400 响应（error: 1、message: lpoint parameter error）。

成功时的响应以信封结构返回：

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

请求/响应的完整 Schema 以及实际调用测试，可在 FX API 演练场的 beamforming 分组中确认。包括 index_l 在内的各波束成形设置值的属性，请参阅波束成形参数文档。

限制与边界值

垂直分辨率压缩会伴随信息丢失。 由于所提供的各压缩、还原函数仅将垂直方向压缩为一半，原本不同的两个索引可能被映射为相同的值。例如 0 与 40 在压缩时都会变为 599，1159 与 1199 都会变为 0。

还原函数始终以上方一行为基准进行还原。 还原函数在还原压缩后的索引时，以原本可能存在的两行中的上方（y * 2）一行为基准进行还原，然后再次反转坐标系（1199 - result）。

因此，在显示 API 响应或结果时，可能会比用户所认知的位置略有偏移，若需要精确还原，可能需要在压缩前另行保存原始坐标信息。

边界值处理摘要

下表中的是否完美还原是指压缩（Downsize）后再还原（Upsize）时，是否能原样得到最初输入的索引。例如 0 被压缩为 599 后还原为 40，因此为 ❌；而 40 同样被压缩为 599，但还原结果仍为 40，因此为 ✅。

输入值压缩结果还原结果是否完美还原
059940❌（可能冲突）
4059940✅
115901199❌（可能冲突）
1160391160✅
119901199✅

概括而言，以反转后的坐标系（1199 - n）为基准，位于偶数 y 行的索引可以被完美还原。