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
+132
View File
@@ -0,0 +1,132 @@
#!/usr/bin/env python3
"""生成 QFT 分辨率楔形标定图。
python scripts/wedge_gen.py --width 1920 --height 1080 --out out/wedge
产出三个文件:
<out>.png 标定图本体(必须 1:1 显示,任何缩放都会让测量失效)
<out>.json 规格,wedge_analyze.py 用它反解几何与期望比特
<out>.html 全屏 1:1 查看器,自带缩放校验
显示方法(二选一):
A. 用浏览器打开 <out>.html,按 F11 全屏。页面会显示「缩放 1.000 ✅」才算有效。
B. 任何能保证 100% 原始像素显示的看图工具,且系统 DPI 缩放为 100%。
拍摄方法:
- 手机大致正立(旋转 < 45°),让四个黑色角标都在画面内且尽量填满画面;
- 关闭闪光灯,对焦到屏幕上;
- 建议在 2~4 个不同距离各拍一张,这样能把 px/模块 曲线的采样点连起来。
"""
import argparse
import os
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from wedge_common import build_spec, render, DEFAULT_PITCHES, DEFAULT_SEED # noqa: E402
VIEWER_HTML = """<!doctype html>
<meta charset="utf-8">
<title>QFT 标定图 1:1 查看器</title>
<style>
html,body{margin:0;padding:0;background:#fff;overflow:hidden}
#wrap{position:absolute;inset:0;display:flex;align-items:center;justify-content:center}
img{image-rendering:pixelated;image-rendering:crisp-edges}
#hud{position:fixed;left:8px;top:8px;font:13px/1.5 ui-monospace,Consolas,monospace;
background:rgba(0,0,0,.82);color:#fff;padding:8px 12px;border-radius:6px;z-index:9}
#hud.bad{background:rgba(150,20,20,.92)}
#hud b{color:#8f8}
#hud.bad b{color:#fbb}
</style>
<div id="wrap"><img id="img" src="__PNG__" alt=""></div>
<div id="hud">测量中…(按 H 隐藏此框,F11 全屏)</div>
<script>
const img = document.getElementById('img'), hud = document.getElementById('hud');
function check(){
const dpr = window.devicePixelRatio || 1;
// 让 1 个图像像素 == 1 个设备像素
img.style.width = (img.naturalWidth / dpr) + 'px';
img.style.height = (img.naturalHeight / dpr) + 'px';
const rect = img.getBoundingClientRect();
const shownDevicePx = rect.width * dpr;
const scale = shownDevicePx / img.naturalWidth;
const screenW = Math.round(window.screen.width * dpr);
const screenH = Math.round(window.screen.height * dpr);
const fits = img.naturalWidth <= screenW && img.naturalHeight <= screenH;
const ok = Math.abs(scale - 1) < 0.002 && fits;
hud.className = ok ? '' : 'bad';
hud.innerHTML =
'图像 ' + img.naturalWidth + '×' + img.naturalHeight +
' · 屏幕设备像素 ' + screenW + '×' + screenH +
' · DPR ' + dpr.toFixed(3) +
' · 缩放 <b>' + scale.toFixed(3) + (ok ? ' ✅</b>' : ' ❌</b>') +
(fits ? '' : '<br>标定图大于屏幕,请用 --width/--height 重新生成为屏幕设备像素尺寸') +
(Math.abs(scale-1) < 0.002 ? '' : '<br>浏览器缩放不是 100%,请按 Ctrl+0 复位');
}
img.complete ? check() : img.addEventListener('load', check);
addEventListener('resize', check);
addEventListener('keydown', e => {
if (e.key === 'h' || e.key === 'H') hud.style.display = hud.style.display === 'none' ? '' : 'none';
});
</script>
"""
def main() -> int:
parser = argparse.ArgumentParser(description="生成 QFT 分辨率楔形标定图")
parser.add_argument("--width", type=int, default=1920, help="画布宽(显示设备像素)")
parser.add_argument("--height", type=int, default=1080, help="画布高(显示设备像素)")
parser.add_argument("--pitches", type=str, default=",".join(str(p) for p in DEFAULT_PITCHES),
help="各条带的模块尺寸,单位显示像素,逗号分隔(必须为整数)")
parser.add_argument("--seed", type=int, default=DEFAULT_SEED)
parser.add_argument("--out", type=str, default="out/wedge", help="输出前缀,不带扩展名")
args = parser.parse_args()
try:
pitches = [int(p) for p in args.pitches.split(",") if p.strip()]
except ValueError:
print("--pitches 必须是逗号分隔的整数", file=sys.stderr)
return 2
try:
spec = build_spec(args.width, args.height, pitches, args.seed)
except ValueError as exc:
print("规格无效:%s" % exc, file=sys.stderr)
return 2
from PIL import Image
canvas = render(spec)
out_dir = os.path.dirname(os.path.abspath(args.out))
if out_dir:
os.makedirs(out_dir, exist_ok=True)
png_path = args.out + ".png"
json_path = args.out + ".json"
html_path = args.out + ".html"
Image.fromarray(canvas).save(png_path, optimize=True)
with open(json_path, "w", encoding="utf-8") as fh:
fh.write(spec.to_json())
with open(html_path, "w", encoding="utf-8") as fh:
fh.write(VIEWER_HTML.replace("__PNG__", os.path.basename(png_path)))
print("已生成:")
print(" %s %d×%d" % (png_path, spec.canvas_w, spec.canvas_h))
print(" %s" % json_path)
print(" %s ← 用浏览器打开并按 F11 全屏" % html_path)
print()
print("条带(模块尺寸以显示像素计):")
total = 0
for band in spec.bands:
total += band.modules
print(" #%d pitch=%2d px %4d×%-3d = %6d 模块"
% (band.index, band.pitch_px, band.cols, band.rows, band.modules))
print(" 合计 %d 模块" % total)
print()
print("拍摄后运行:python scripts/wedge_analyze.py --spec %s --photo <照片>" % json_path)
return 0
if __name__ == "__main__":
raise SystemExit(main())