Files
QFT/scripts/wedge_common.py
zhy200308 ea7b678b37 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。
故需改为「内码纠错 + 外层喷泉码纠删」的级联结构,已记入文档。
2026-08-11 09:08:04 +08:00

230 lines
7.5 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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)