@ray-js/ipc-player-integration 0.0.49 → 0.0.50-beta.0

package/lib/widgets/zoomTurntable/lensModel.test.js

@@ -0,0 +1,336 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.filter.js";
+import "core-js/modules/esnext.iterator.map.js";
+import { DEFAULT_MATCH_TOLERANCE, D_MAX, D_MIN, buildMarks, buildTickValues, deltaOf, indexOfLensId, matchLens, maxScaleMultiple, toDisplayZoom, toleranceOf, toScaleMultiple, zoomBounds } from './lensModel';
+import { isZoomSkillValid, lensCount, parseZoomSkill } from './lensSkill';
+
+/** 双目定焦：短焦 1.0x / 临界 3.0x / 长焦 3.0x / 手势上限 6.0x */
+const DOUBLE = {
+  cnt: 2,
+  thresholds: [1.0, 3.0, 6.0],
+  lenses: [{
+    id: 0,
+    type: 1,
+    step: 0.1,
+    basicRatio: 1.0
+  }, {
+    id: 1,
+    type: 1,
+    step: 0.1,
+    basicRatio: 3.0
+  }]
+};
+
+/** 三目定焦 */
+const TRIPLE = {
+  cnt: 3,
+  thresholds: [1.0, 3.0, 6.0, 12.0],
+  lenses: [{
+    id: 0,
+    type: 1,
+    step: 0.1,
+    basicRatio: 1.0
+  }, {
+    id: 1,
+    type: 1,
+    step: 0.1,
+    basicRatio: 3.0
+  }, {
+    id: 2,
+    type: 1,
+    step: 0.1,
+    basicRatio: 6.0
+  }]
+};
+describe('lensSkill 校验', () => {
+  it('cnt 为镜头数依据，缺失时回落 lenses.length', () => {
+    expect(lensCount(DOUBLE)).toBe(2);
+    expect(lensCount(_objectSpread(_objectSpread({}, DOUBLE), {}, {
+      cnt: undefined
+    }))).toBe(2);
+    expect(lensCount(null)).toBe(0);
+    expect(lensCount({
+      cnt: 2,
+      thresholds: [],
+      lenses: []
+    })).toBe(0);
+  });
+  it('合法数据通过校验', () => {
+    expect(isZoomSkillValid(DOUBLE)).toBe(true);
+    expect(isZoomSkillValid(TRIPLE)).toBe(true);
+  });
+  it('畸形数据一律判不可用（不做部分降级）', () => {
+    // thresholds 长度不等于 cnt + 1
+    expect(isZoomSkillValid(_objectSpread(_objectSpread({}, DOUBLE), {}, {
+      thresholds: [1, 3]
+    }))).toBe(false);
+    // thresholds 非升序
+    expect(isZoomSkillValid(_objectSpread(_objectSpread({}, DOUBLE), {}, {
+      thresholds: [1, 6, 3]
+    }))).toBe(false);
+    // 单镜头（门控在 useLensZoom 里，这里只验校验函数本身仍认为数据合法）
+    expect(isZoomSkillValid({
+      cnt: 1,
+      thresholds: [1, 6],
+      lenses: [{
+        id: 0,
+        type: 1,
+        basicRatio: 1
+      }]
+    })).toBe(true);
+    expect(isZoomSkillValid(null)).toBe(false);
+  });
+});
+describe('ipc_multi_zoom 上报值解析', () => {
+  /** 协议参考上报值 */
+
+  it('解析上报 string，cnt 即镜头数', () => {
+    const skill = parseZoomSkill('{"cnt":2,"thresholds":[1,3,6],"lenses":[{"id":0,"type":0,"step":0.1,"basicRatio":1},{"id":1,"type":1,"step":0.1,"basicRatio":3}]}');
+    expect(lensCount(skill)).toBe(2);
+    expect(isZoomSkillValid(skill)).toBe(true);
+    expect(skill.lenses[1]).toEqual({
+      id: 1,
+      type: 1,
+      step: 0.1,
+      basicRatio: 3
+    });
+    expect(zoomBounds(skill)).toEqual([1, 6]);
+  });
+  it('对象值直接透传（调试注入 mockZoomSkill）', () => {
+    expect(parseZoomSkill(DOUBLE)).toBe(DOUBLE);
+  });
+  it('空值 / 畸形 JSON 返回 null，不抛错', () => {
+    expect(parseZoomSkill(undefined)).toBeNull();
+    expect(parseZoomSkill('')).toBeNull();
+    expect(parseZoomSkill('not json')).toBeNull();
+    expect(parseZoomSkill(2)).toBeNull();
+  });
+  it('单镜头设备（cnt = 1）不具备多镜头能力', () => {
+    const single = parseZoomSkill('{"cnt":1,"thresholds":[1,3],"lenses":[{"id":0,"type":0,"step":0.1,"basicRatio":1}]}');
+    expect(lensCount(single)).toBe(1);
+  });
+});
+describe('双层缩放换算', () => {
+  it('Δ 由 thresholds 区间跨度推导', () => {
+    // d ∈ [1, 4]，lens0: (3-1)/(4-1) ≈ 0.667    lens1: (6-3)/(4-1) = 1.0
+    expect(deltaOf(DOUBLE, 0)).toBeCloseTo(2 / 3);
+    expect(deltaOf(DOUBLE, 1)).toBeCloseTo(1.0);
+  });
+  it('长焦区间 [3,6] 上 d 与画面倍率 1:1 递增', () => {
+    // 协议参考值：3 为 1 倍、4 为 2 倍、5 为 3 倍、6 为 4 倍
+    expect(toDisplayZoom(DOUBLE, 1, 1.0)).toBeCloseTo(3.0);
+    expect(toDisplayZoom(DOUBLE, 1, 2.0)).toBeCloseTo(4.0);
+    expect(toDisplayZoom(DOUBLE, 1, 3.0)).toBeCloseTo(5.0);
+    expect(toDisplayZoom(DOUBLE, 1, 4.0)).toBeCloseTo(6.0);
+  });
+  it('回读：同一个 d 在不同镜头上换算出不同画面倍率', () => {
+    // d=2.0 在短焦是画面 1.67x，在长焦是画面 4.0x —— 直接显示 d 就是错的
+    expect(toDisplayZoom(DOUBLE, 0, 2.0)).toBeCloseTo(1 + 2 / 3);
+    expect(toDisplayZoom(DOUBLE, 1, 2.0)).toBeCloseTo(4.0);
+  });
+  it('回读：d 边界对应镜头区间端点', () => {
+    expect(toDisplayZoom(DOUBLE, 0, D_MIN)).toBeCloseTo(1.0);
+    expect(toDisplayZoom(DOUBLE, 0, D_MAX)).toBeCloseTo(3.0);
+    expect(toDisplayZoom(DOUBLE, 1, D_MIN)).toBeCloseTo(3.0);
+    expect(toDisplayZoom(DOUBLE, 1, D_MAX)).toBeCloseTo(6.0);
+  });
+  it('回读：d 超出 [1,4] 被夹住，不溢出区间', () => {
+    expect(toDisplayZoom(DOUBLE, 0, 0.2)).toBeCloseTo(1.0);
+    expect(toDisplayZoom(DOUBLE, 0, 99)).toBeCloseTo(3.0);
+  });
+  it('往返自洽：toScaleMultiple(toDisplayZoom(d)) === d', () => {
+    [0, 1].forEach(index => {
+      [1.0, 1.5, 2.0, 2.7, 3.0, 4.0].forEach(d => {
+        const curM = toDisplayZoom(DOUBLE, index, d);
+        expect(toScaleMultiple(DOUBLE, index, curM)).toBeCloseTo(d, 5);
+      });
+    });
+  });
+  it('往返自洽：toDisplayZoom(toScaleMultiple(curM)) === curM', () => {
+    [1.0, 1.8, 2.9, 3.0].forEach(curM => {
+      expect(toDisplayZoom(DOUBLE, 0, toScaleMultiple(DOUBLE, 0, curM))).toBeCloseTo(curM, 5);
+    });
+    [3.0, 4.5, 5.2, 6.0].forEach(curM => {
+      expect(toDisplayZoom(DOUBLE, 1, toScaleMultiple(DOUBLE, 1, curM))).toBeCloseTo(curM, 5);
+    });
+  });
+  it('增减法而非乘法：长焦顶格是 3+3=6，不是 3×4=12', () => {
+    expect(toDisplayZoom(DOUBLE, 1, D_MAX)).toBeCloseTo(6.0);
+    expect(toDisplayZoom(DOUBLE, 1, D_MAX)).not.toBeCloseTo(12.0);
+  });
+});
+describe('镜头匹配', () => {
+  it('区间内正常命中', () => {
+    expect(matchLens(DOUBLE, 1.0)).toBe(0);
+    expect(matchLens(DOUBLE, 2.5)).toBe(0);
+    expect(matchLens(DOUBLE, 4.0)).toBe(1);
+    expect(matchLens(DOUBLE, 6.0)).toBe(1);
+  });
+  it('临界点归大镜头，避免横跳', () => {
+    // 3.0 同时落在 lens0 [1,3] 与 lens1 [3,6]，取 basicRatio 大者
+    expect(matchLens(DOUBLE, 3.0)).toBe(1);
+  });
+  it('容差取镜头 step（0.1）：2.9 起进长焦，2.8 仍在短焦', () => {
+    expect(matchLens(DOUBLE, 2.9)).toBe(1); // 2.9 在 lens1 的 [2.9, 6.1] 容差内 → 归大镜头
+    expect(matchLens(DOUBLE, 2.8)).toBe(0); // 超出 lens1 容差下界 → 短焦
+    expect(matchLens(DOUBLE, 3.1)).toBe(1);
+  });
+  it('容差随各镜头 step 变化，未声明 step 时用缺省 0.1', () => {
+    const coarse = {
+      cnt: 2,
+      thresholds: [1.0, 3.0, 6.0],
+      lenses: [{
+        id: 0,
+        type: 1,
+        step: 0.1,
+        basicRatio: 1.0
+      }, {
+        id: 1,
+        type: 1,
+        step: 0.5,
+        basicRatio: 3.0
+      } // 长焦步进更粗
+      ]
+    };
+    expect(toleranceOf(coarse, 1)).toBe(0.5);
+    expect(matchLens(coarse, 2.6)).toBe(1); // 落在 lens1 的 [2.5, 6.5] 内
+    expect(matchLens(coarse, 2.4)).toBe(0);
+    const noStep = {
+      cnt: 2,
+      thresholds: [1.0, 3.0, 6.0],
+      lenses: [{
+        id: 0,
+        type: 1,
+        basicRatio: 1.0
+      }, {
+        id: 1,
+        type: 1,
+        basicRatio: 3.0
+      }]
+    };
+    expect(toleranceOf(noStep, 1)).toBe(DEFAULT_MATCH_TOLERANCE);
+    expect(matchLens(noStep, 2.9)).toBe(1);
+    expect(matchLens(noStep, 2.8)).toBe(0);
+  });
+  it('三目：跨两次临界点', () => {
+    expect(matchLens(TRIPLE, 1.5)).toBe(0);
+    expect(matchLens(TRIPLE, 4.0)).toBe(1);
+    expect(matchLens(TRIPLE, 9.0)).toBe(2);
+    expect(matchLens(TRIPLE, 6.0)).toBe(2); // 临界归大
+  });
+  it('镜头 id 反查下标', () => {
+    expect(indexOfLensId(DOUBLE, 1)).toBe(1);
+    expect(indexOfLensId(DOUBLE, 99)).toBe(0); // 找不到回落 0
+  });
+});
+describe('次刻度按各镜头 step 分段生成', () => {
+  /** 分段 step 不同：短焦 step 0.1、长焦 step 0.3 */
+  const MIXED_STEP = {
+    cnt: 2,
+    thresholds: [1.0, 3.0, 6.0],
+    lenses: [{
+      id: 0,
+      type: 1,
+      step: 0.1,
+      basicRatio: 1.0
+    }, {
+      id: 1,
+      type: 1,
+      step: 0.3,
+      basicRatio: 3.0
+    }]
+  };
+  it('双目：[1,3] 每 0.1 一格，[3,6] 每 0.3 一格', () => {
+    const ticks = buildTickValues(MIXED_STEP);
+    expect(ticks.filter(value => value <= 3)).toEqual([1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3]);
+    expect(ticks.filter(value => value >= 3)).toEqual([3, 3.3, 3.6, 3.9, 4.2, 4.5, 4.8, 5.1, 5.4, 5.7, 6]);
+  });
+  it('刻度升序、无重复、不越过上限', () => {
+    const ticks = buildTickValues(MIXED_STEP);
+    expect(ticks).toEqual([...ticks].sort((a, b) => a - b));
+    expect(new Set(ticks).size).toBe(ticks.length);
+    expect(Math.max(...ticks)).toBeCloseTo(6);
+  });
+  it('临界点只出现一次（相邻区间共用端点）', () => {
+    expect(buildTickValues(MIXED_STEP).filter(value => value === 3)).toHaveLength(1);
+  });
+  it('三目：三段各按自己的 step', () => {
+    expect(buildTickValues({
+      cnt: 3,
+      thresholds: [1, 3, 6, 12],
+      lenses: [{
+        id: 0,
+        type: 1,
+        step: 0.5,
+        basicRatio: 1
+      }, {
+        id: 1,
+        type: 1,
+        step: 1,
+        basicRatio: 3
+      }, {
+        id: 2,
+        type: 1,
+        step: 2,
+        basicRatio: 6
+      }]
+    })).toEqual([1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 12]);
+  });
+  it('step 缺失时该段用缺省 0.1', () => {
+    expect(buildTickValues({
+      cnt: 1,
+      thresholds: [1, 1.5],
+      lenses: [{
+        id: 0,
+        type: 1,
+        basicRatio: 1
+      }]
+    })).toEqual([1, 1.1, 1.2, 1.3, 1.4, 1.5]);
+  });
+});
+describe('手势缩放上限按镜头换算', () => {
+  it('取该镜头区间上限对应的 d，受 D_MAX 约束', () => {
+    expect(maxScaleMultiple(DOUBLE, 0)).toBeCloseTo(D_MAX);
+    expect(maxScaleMultiple(DOUBLE, 1)).toBeCloseTo(D_MAX);
+    expect(maxScaleMultiple(TRIPLE, 2)).toBeCloseTo(D_MAX);
+  });
+  it('换算结果落在镜头区间上限上（回代 toDisplayZoom 自洽）', () => {
+    expect(toDisplayZoom(DOUBLE, 0, maxScaleMultiple(DOUBLE, 0))).toBeCloseTo(3.0);
+    expect(toDisplayZoom(DOUBLE, 1, maxScaleMultiple(DOUBLE, 1))).toBeCloseTo(6.0);
+  });
+});
+describe('转盘区间与刻度', () => {
+  it('区间取 thresholds 首尾（不使用 maxZoomSettings）', () => {
+    expect(zoomBounds(DOUBLE)).toEqual([1.0, 6.0]);
+    expect(zoomBounds(TRIPLE)).toEqual([1.0, 12.0]);
+  });
+  it('主刻度 = 各镜头光学倍数 + 上限，去重升序', () => {
+    expect(buildMarks(DOUBLE)).toEqual([{
+      value: 1,
+      label: '1'
+    }, {
+      value: 3,
+      label: '3'
+    }, {
+      value: 6,
+      label: '6'
+    }]);
+    expect(buildMarks(TRIPLE).map(mark => mark.value)).toEqual([1, 3, 6, 12]);
+  });
+  it('非整数倍率保留一位小数', () => {
+    expect(buildMarks({
+      cnt: 2,
+      thresholds: [1.0, 2.5, 5.0],
+      lenses: [{
+        id: 0,
+        type: 1,
+        basicRatio: 1.0
+      }, {
+        id: 1,
+        type: 1,
+        basicRatio: 2.5
+      }]
+    }).map(mark => mark.label)).toEqual(['1', '2.5', '5']);
+  });
+});

package/lib/widgets/zoomTurntable/lensSkill.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 镜头能力解析与镜头切换下发。协议相关的不确定性都收敛在本文件。
+ *
+ * 协议来源：《面板小程序 V1.6.0_零散优化+多目变焦》§4
+ *
+ * 能力取自 ipc_multi_zoom DP 的 string 值，cnt <= 1 不出现转盘入口：
+ *   {"cnt":2,"thresholds":[1,3,6],"lenses":[{"id":0,"type":0,"step":0.1,"basicRatio":1},…]}
+ * 切镜头走 ty.ipc.switchChannel({ deviceId, channel })，channel 即上报的子镜头 id。
+ * 出流后用 ty.ipc.queryCurrentChannel 回读当前镜头；
+ * 设备侧 / 其他端切镜头由 ty.ipc.onChannelChange 事件通知。
+ */
+export type Lens = {
+    /** 镜头 ID；切镜头时作为 ty.ipc.switchChannel 的 channel 下发 */
+    id: number;
+    /** 0 球机(PTZ) · 1 枪机(Bullet) */
+    type: 0 | 1;
+    /** 镜头固定光学倍数（定焦）；按钮显示 + 双层 base + 下发目标倍数 */
+    basicRatio: number;
+    /** 步进精度 */
+    step?: number;
+};
+export type ZoomSkill = {
+    /** 镜头数量（= 按钮数），协议保证与 lenses.length 一致；统一经 lensCount() 取用 */
+    cnt?: number;
+    /** [起始, 切换点…, 手势放大上限]，长度 = cnt + 1，升序 */
+    thresholds: number[];
+    /** 镜头数组，按 basicRatio 升序 */
+    lenses: Lens[];
+};
+export type CurrentLensState = {
+    /** 对应 Lens.id */
+    lens_id: number;
+    /** 当前本地数字缩放 d；宿主不回该字段时按 1.0 处理 */
+    multiple: number;
+};
+/** channelChange 事件载荷 */
+export type ChannelChangeEvent = {
+    /** 设备 id；宿主未带该字段时不做设备过滤 */
+    deviceId?: string;
+    /** 切换后的镜头通道，对应 Lens.id */
+    channel: number;
+};
+/** 能力 DP：其 string 值即镜头能力描述，解析出的 cnt > 1 才显示入口 */
+export { MULTI_ZOOM as MULTI_ZOOM_DP_CODE } from '../../utils/content/dpCode';
+/** MOCK 数据：与协议参考上报值一致的双目定焦（短焦 1.0x / 临界 3.0x / 上限 6.0x） */
+export declare const MOCK_ZOOM_SKILL: ZoomSkill;
+/**
+ * 镜头数量。以 cnt 为判定字段；
+ * 固件漏填时回落到 lenses.length，两者不一致时告警（协议保证一致）。
+ */
+export declare const lensCount: (skill?: ZoomSkill | null) => number;
+/** 校验数据自洽性。半套数据画出的刻度是错的，比不显示更糟，故不做部分降级 */
+export declare const isZoomSkillValid: (skill?: ZoomSkill | null) => boolean;
+/**
+ * 解析 ipc_multi_zoom DP 上报的 string 值为镜头能力。
+ * @param value DP 值；调试注入的对象（mockZoomSkill）直接透传，两条来源共用同一校验链路
+ */
+export declare const parseZoomSkill: (value?: unknown) => ZoomSkill | null;
+/**
+ * 切换物理镜头。channel 取上报的子镜头 id 而非数组下标 —— 固件可上报非连续 id。
+ * 返回 false（不支持 / 失败）时由 useLensZoom 回滚读数，无回调另有 SWITCH_LENS_TIMEOUT 兜底。
+ */
+export declare const switchLens: (devId: string, lens: Lens) => Promise<boolean>;
+/** 打印播放器实例上的方法名；方法名对不上时用来确认实例究竟提供了什么 */
+export declare const dumpPlayerApis: (IPCPlayerInstance: any, keyword?: string) => void;
+/**
+ * 开关全景小窗（小窗画面为当前镜头的全景）。
+ *
+ * 画面停在镜头光学正倍数上时不需要小窗，在镜头区间内数字放大后才需要。
+ * 调用方（useLensZoom）已按 devId 做过去重，这里只管下发，不判重。
+ */
+export declare const showSmallMonitor: (IPCPlayerInstance: any, show: boolean) => void;
+/**
+ * 查询当前镜头与本地缩放，用于出流后 / 重连后同步。
+ * 返回 null（不支持 / 失败 / 超时）时调用方保持现状，不重置镜头。
+ */
+export declare const queryCurrentLens: (devId: string) => Promise<CurrentLensState | null>;
+/**
+ * 宿主是否支持镜头切换事件。
+ * 切镜头的收尾（画面归 1 倍 + 刷读数）以该事件为准，不支持时只能退回「switchChannel 成功即收尾」。
+ */
+export declare const isChannelChangeSupported: () => boolean;
+/**
+ * 打印 ty.ipc 上与 channel 相关的方法名（顺原型链收集，方法可能挂在原型上）。
+ * 真机上「事件为什么不来」第一步就是确认宿主到底提供了哪个名字。
+ */
+export declare const dumpChannelApis: () => void;
+/** 订阅镜头切换事件（自己下发 / 设备侧 / 其他端切镜头都会上报），返回取消订阅函数 */
+export declare const subscribeChannelChange: (devId: string, handler: (e: ChannelChangeEvent) => void) => (() => void);