feat: 新增 QFT5 光学链路方案与分辨率楔形标定工具

当前光学链路传 3MB 需要 1 小时,瓶颈不是解码慢而是无反馈重传浪费:
按 320B 分片、45FPS 反推,每轮约捕获 44%,收齐需 16.5 轮,
约 86% 的信道被已收到的重复分片占用。

docs/OPTICAL_V5_PLAN.md 给出完整改造方案:
- 条带级喷泉码消除重传浪费,撕裂只损失 1/12 而非整帧
- MANIFEST 每 32~64 帧插播,消除平均 109 秒的启动空转
- 相机帧率三级锁定 + 手动短曝光(3px/模块下 33ms 自动曝光
  会产生 8.7px 运动模糊,等于抹掉近 3 个模块,必然解不出)
- 陀螺仪前馈跟踪四角单应,解决手持抖动丢锁
- 位阵列替代 QR,突破 v40 的 177 模块上限

scripts/wedge_*.py 是配套标定工具。方案里所有吞吐数字都建立在
「px/模块 的真实下限」这一未实测假设上,而合成实验显示该值仅因
对焦质量不同就能在 3.1~5.7 之间摆动,必须先实测:
- wedge_gen.py     生成 7 档 pitch 的伪随机标定图 + 1:1 全屏查看器
- wedge_analyze.py 照片 → 实测 px/模块 → 对比度 → 误码率曲线
- wedge_selftest.py 合成相机模型端到端自检,无需真实硬件

标定同时暴露了方案的一个缺口:条带只有 CRC 没有内码,1750B 条带
约 14000 bit,1 bit 错即整条报废,要求原始 BER 低于 1e-5。
故需改为「内码纠错 + 外层喷泉码纠删」的级联结构,已记入文档。
This commit is contained in:
zhy200308
2026-08-11 09:08:04 +08:00
parent 0b7ffd2dab
commit ea7b678b37
7 changed files with 1405 additions and 0 deletions
+229
View File
@@ -0,0 +1,229 @@
#!/usr/bin/env python3
"""QFT 分辨率楔形标定图 —— 共享规格、PRNG 与渲染。
用途:在屏幕上显示一张同时包含多种模块尺寸(pitch)的伪随机二值图案,
手机拍一张照片,由 wedge_analyze.py 反解出「每模块相机像素数 → 误码率」曲线,
从而实测出本套硬件真正的 px/模块 下限。这个下限直接决定 QFT5 位阵列的容量。
坐标系
------
canvas 坐标:整张标定图的像素坐标,原点左上。
active 坐标:以左上角基准标**中心**为原点的坐标系;四个基准标中心构成 active 矩形。
分析端解出的单应矩阵就是 active → 照片像素 的映射,因此所有条带几何
都用 active 坐标描述,与画布边距无关。
约定
----
- 模块 bit == 1 → 黑 (0),bit == 0 → 白 (255)。
- PRNG 为 SplitMix64,Rust / Kotlin 移植时必须逐位一致(见 splitmix64)。
- 模块 (r, c) 的比特序号 k = r * cols + c;取第 k//64 个 64 位输出的第 k%64 位(LSB 起)。
"""
from dataclasses import dataclass, asdict
from typing import List, Optional
import json
MASK64 = (1 << 64) - 1
GOLDEN = 0x9E3779B97F4A7C15
SPEC_VERSION = 1
DEFAULT_PITCHES = [10, 8, 6, 5, 4, 3, 2]
DEFAULT_SEED = 20260810
# 画布留白与基准标尺寸(canvas 像素)
MARGIN_PX = 40
MARKER_PX = 56
INSET_PX = 64 # 数据区相对 active 矩形的内缩,保证基准标周围留白
GUTTER_PX = 8 # 条带间隔
def splitmix64(state: int):
"""SplitMix64 生成器。返回 (下一状态, 64 位输出)。"""
state = (state + GOLDEN) & MASK64
z = state
z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & MASK64
z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & MASK64
return state, z ^ (z >> 31)
def band_seed(seed: int, index: int) -> int:
return (seed ^ ((GOLDEN * (index + 1)) & MASK64)) & MASK64
@dataclass
class BandSpec:
index: int
pitch_px: int
cols: int
rows: int
x: int # active 坐标
y: int
seed: int
@property
def width_px(self) -> int:
return self.cols * self.pitch_px
@property
def height_px(self) -> int:
return self.rows * self.pitch_px
@property
def modules(self) -> int:
return self.cols * self.rows
@dataclass
class WedgeSpec:
version: int
canvas_w: int
canvas_h: int
margin_px: int
marker_px: int
inset_px: int
gutter_px: int
seed: int
active_w: int # active 矩形尺寸(= 基准标中心间距)
active_h: int
bands: List[BandSpec]
def to_json(self, indent: Optional[int] = 2) -> str:
payload = asdict(self)
return json.dumps(payload, indent=indent, ensure_ascii=False)
@staticmethod
def from_dict(payload: dict) -> "WedgeSpec":
bands = [BandSpec(**b) for b in payload["bands"]]
rest = {k: v for k, v in payload.items() if k != "bands"}
return WedgeSpec(bands=bands, **rest)
@staticmethod
def load(path) -> "WedgeSpec":
with open(path, "r", encoding="utf-8") as fh:
return WedgeSpec.from_dict(json.load(fh))
def marker_centers_canvas(self):
"""四个基准标中心在 canvas 坐标下的位置,顺序 TL, TR, BR, BL。"""
half = self.marker_px / 2.0
x0 = self.margin_px + half
y0 = self.margin_px + half
x1 = self.canvas_w - self.margin_px - half
y1 = self.canvas_h - self.margin_px - half
return [(x0, y0), (x1, y0), (x1, y1), (x0, y1)]
def active_corners(self):
"""active 坐标下的四角,顺序与 marker_centers_canvas 一致。"""
return [(0.0, 0.0), (float(self.active_w), 0.0),
(float(self.active_w), float(self.active_h)), (0.0, float(self.active_h))]
def build_spec(canvas_w: int = 1920,
canvas_h: int = 1080,
pitches: Optional[List[int]] = None,
seed: int = DEFAULT_SEED,
margin_px: int = MARGIN_PX,
marker_px: int = MARKER_PX,
inset_px: int = INSET_PX,
gutter_px: int = GUTTER_PX) -> WedgeSpec:
pitches = list(pitches or DEFAULT_PITCHES)
if not pitches:
raise ValueError("至少需要一个 pitch")
if any(p < 1 for p in pitches):
raise ValueError("pitch 必须 >= 1 显示像素")
active_w = canvas_w - 2 * margin_px - marker_px
active_h = canvas_h - 2 * margin_px - marker_px
data_w = active_w - 2 * inset_px
data_h = active_h - 2 * inset_px
if data_w < 64 or data_h < 64:
raise ValueError("画布太小,数据区不足")
n = len(pitches)
band_h = (data_h - (n - 1) * gutter_px) // n
if band_h < max(pitches):
raise ValueError("画布高度不足以容纳全部条带")
bands: List[BandSpec] = []
for i, pitch in enumerate(pitches):
cols = data_w // pitch
rows = band_h // pitch
if cols < 8 or rows < 2:
raise ValueError("pitch %d 下条带尺寸过小" % pitch)
bands.append(BandSpec(
index=i,
pitch_px=pitch,
cols=cols,
rows=rows,
x=inset_px,
y=inset_px + i * (band_h + gutter_px),
seed=band_seed(seed, i),
))
return WedgeSpec(
version=SPEC_VERSION,
canvas_w=canvas_w,
canvas_h=canvas_h,
margin_px=margin_px,
marker_px=marker_px,
inset_px=inset_px,
gutter_px=gutter_px,
seed=seed,
active_w=active_w,
active_h=active_h,
bands=bands,
)
def band_bits(band: BandSpec):
"""返回形状 (rows, cols) 的 uint8 数组,1 = 黑模块。"""
import numpy as np
total = band.modules
words = (total + 63) // 64
state = band.seed
out = np.empty(words, dtype=np.uint64)
for i in range(words):
state, value = splitmix64(state)
out[i] = value
bits = np.unpackbits(out.view(np.uint8).reshape(words, 8), axis=1, bitorder="little")
# view(uint8) 在小端机器上给出 LSB->MSB 的字节序,配合 bitorder="little"
# 即得到 k 递增方向的比特流。
bits = bits.reshape(-1)[:total]
return bits.reshape(band.rows, band.cols)
def render(spec: WedgeSpec):
"""渲染整张标定图,返回 (H, W) 的 uint8 灰度数组。"""
import numpy as np
canvas = np.full((spec.canvas_h, spec.canvas_w), 255, dtype=np.uint8)
# active 原点在 canvas 中的位置 = 左上基准标中心
ox = spec.margin_px + spec.marker_px / 2.0
oy = spec.margin_px + spec.marker_px / 2.0
# 四个实心黑方块基准标,中心落在 active 四角
half = spec.marker_px // 2
for cx, cy in spec.marker_centers_canvas():
x0, y0 = int(round(cx)) - half, int(round(cy)) - half
canvas[y0:y0 + spec.marker_px, x0:x0 + spec.marker_px] = 0
for band in spec.bands:
bits = band_bits(band)
block = np.repeat(np.repeat(bits, band.pitch_px, axis=0), band.pitch_px, axis=1)
px = int(round(ox + band.x))
py = int(round(oy + band.y))
canvas[py:py + block.shape[0], px:px + block.shape[1]] = np.where(block == 1, 0, 255)
return canvas
def module_centers_active(band: BandSpec, spec: WedgeSpec):
"""返回该条带全部模块中心的 active 坐标,形状 (rows, cols, 2)。"""
import numpy as np
del spec # 条带 x/y 已是 active 坐标,无需画布信息
cx = band.x + (np.arange(band.cols) + 0.5) * band.pitch_px
cy = band.y + (np.arange(band.rows) + 0.5) * band.pitch_px
gx, gy = np.meshgrid(cx, cy)
return np.stack([gx, gy], axis=-1)