Files
QFT/scripts/wedge_analyze.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

447 lines
16 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
"""分析楔形标定图的照片,输出「每模块相机像素数 → 误码率」曲线。
python scripts/wedge_analyze.py --spec out/wedge.json --photo IMG_0001.jpg
流程与真实解码器完全一致,所以测出来的就是真实可用的下限:
检测四角基准标 → 解单应矩阵 → 按模块中心单点采样
→ 局部均值阈值面 → 判决 → 与期望比特比对
--analysis-width 用来模拟手机 ImageAnalysis 流的分辨率(默认 1920,即 1080p)。
照片本身通常是 12MP,直接分析会高估能力;先降采样到分析流分辨率才有意义。
"""
import argparse
import os
import sys
import numpy as np
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from wedge_common import WedgeSpec, band_bits, module_centers_active # noqa: E402
# ---------------------------------------------------------------- 图像载入
def load_gray(path, analysis_width):
from PIL import Image, ImageOps
image = Image.open(path)
image = ImageOps.exif_transpose(image)
image = image.convert("L")
original = image.size
if analysis_width and image.width > analysis_width:
height = max(1, int(round(image.height * analysis_width / image.width)))
# BOX(面积平均)最接近相机 ISP 的降采样行为
image = image.resize((analysis_width, height), Image.BOX)
return np.asarray(image, dtype=np.float32), original
# ---------------------------------------------------------------- 连通域
def otsu(gray):
hist, _ = np.histogram(gray, bins=256, range=(0, 256))
total = hist.sum()
if total == 0:
return 128.0
levels = np.arange(256, dtype=np.float64)
w0 = np.cumsum(hist).astype(np.float64)
w1 = total - w0
s0 = np.cumsum(hist * levels)
total_sum = s0[-1]
valid = (w0 > 0) & (w1 > 0)
if not valid.any():
return 128.0
m0 = np.where(w0 > 0, s0 / np.maximum(w0, 1), 0.0)
m1 = np.where(w1 > 0, (total_sum - s0) / np.maximum(w1, 1), 0.0)
between = w0 * w1 * (m0 - m1) ** 2
between[~valid] = -1.0
return float(np.argmax(between))
def label_components(mask):
"""行程 + 并查集的连通域标记(4 连通)。返回 (labels, count)。"""
height, width = mask.shape
parent = [0]
def find(a):
while parent[a] != a:
parent[a] = parent[parent[a]]
a = parent[a]
return a
def union(a, b):
ra, rb = find(a), find(b)
if ra != rb:
parent[max(ra, rb)] = min(ra, rb)
labels = np.zeros((height, width), dtype=np.int32)
prev_runs = []
for y in range(height):
row = mask[y]
if not row.any():
prev_runs = []
continue
diff = np.diff(np.concatenate(([0], row.view(np.int8), [0])))
starts = np.flatnonzero(diff == 1)
ends = np.flatnonzero(diff == -1)
runs = []
for x0, x1 in zip(starts, ends):
parent.append(len(parent))
current = len(parent) - 1
for px0, px1, plabel in prev_runs:
if px0 < x1 and x0 < px1:
union(current, plabel)
labels[y, x0:x1] = current
runs.append((x0, x1, current))
prev_runs = runs
flat = labels.reshape(-1)
nonzero = flat > 0
if nonzero.any():
roots = np.array([find(i) for i in range(len(parent))], dtype=np.int32)
flat[nonzero] = roots[flat[nonzero]]
unique, remapped = np.unique(flat[nonzero], return_inverse=True)
flat[nonzero] = remapped + 1
count = len(unique)
else:
count = 0
return labels, count
def find_markers(gray, debug=None):
"""返回四个基准标中心(照片像素),顺序 TL, TR, BR, BL。"""
height, width = gray.shape
scale = max(1.0, width / 1200.0)
if scale > 1.0:
from PIL import Image
small = np.asarray(
Image.fromarray(gray.astype(np.uint8)).resize(
(int(width / scale), int(height / scale)), Image.BOX),
dtype=np.float32)
else:
small = gray
threshold = otsu(small)
mask = small < threshold
labels, count = label_components(mask)
if count == 0:
raise RuntimeError("照片里找不到任何暗色区域")
area_image = small.shape[0] * small.shape[1]
candidates = []
for index in range(1, count + 1):
ys, xs = np.nonzero(labels == index)
area = len(xs)
if area < 24 or area > area_image * 0.02:
continue
x0, x1 = xs.min(), xs.max() + 1
y0, y1 = ys.min(), ys.max() + 1
bw, bh = x1 - x0, y1 - y0
aspect = bw / float(bh)
if not 0.55 < aspect < 1.8:
continue
if area / float(bw * bh) < 0.72: # 实心方块
continue
# 外围一圈必须是白的(黑方块落在白底上),排除画面外的暗区与数据模块
pad = int(max(bw, bh) * 0.6) + 2
ry0, ry1 = max(0, y0 - pad), min(small.shape[0], y1 + pad)
rx0, rx1 = max(0, x0 - pad), min(small.shape[1], x1 + pad)
ring = small[ry0:ry1, rx0:rx1].copy()
inner = ring[y0 - ry0:y1 - ry0, x0 - rx0:x1 - rx0]
ring_sum = ring.sum() - inner.sum()
ring_n = ring.size - inner.size
if ring_n <= 0 or ring_sum / ring_n < threshold * 1.15:
continue
candidates.append((area, (xs.mean() + 0.5) * scale, (ys.mean() + 0.5) * scale,
bw * scale, bh * scale))
if len(candidates) < 4:
raise RuntimeError("只找到 %d 个候选基准标(需要 4 个)。"
"请让四个黑色角标全部进入画面,并保持画面明亮、对焦清晰。"
% len(candidates))
candidates.sort(key=lambda c: -c[0])
pool = candidates[:24]
pts = np.array([[c[1], c[2]] for c in pool])
sizes = np.array([max(c[3], c[4]) for c in pool])
def pick(score):
return int(np.argmax(score))
tl = pick(-(pts[:, 0] + pts[:, 1]))
br = pick(pts[:, 0] + pts[:, 1])
tr = pick(pts[:, 0] - pts[:, 1])
bl = pick(pts[:, 1] - pts[:, 0])
chosen = [tl, tr, br, bl]
if len(set(chosen)) != 4:
raise RuntimeError("角标定位歧义,请正对屏幕重拍,避免过大的倾斜")
refined = []
for index in chosen:
cx, cy, size = pts[index, 0], pts[index, 1], sizes[index]
refined.append(refine_centroid(gray, cx, cy, size))
if debug is not None:
debug["markers_raw"] = pts[chosen].tolist()
return refined
def refine_centroid(gray, cx, cy, size):
"""在全分辨率图上做灰度加权质心,取得亚像素中心。"""
half = max(4.0, size * 0.9)
x0 = int(max(0, np.floor(cx - half)))
x1 = int(min(gray.shape[1], np.ceil(cx + half)))
y0 = int(max(0, np.floor(cy - half)))
y1 = int(min(gray.shape[0], np.ceil(cy + half)))
patch = gray[y0:y1, x0:x1]
if patch.size == 0:
return (float(cx), float(cy))
level = otsu(patch)
weight = np.clip(level - patch, 0, None)
total = weight.sum()
if total <= 0:
return (float(cx), float(cy))
ys, xs = np.mgrid[y0:y1, x0:x1]
return (float((weight * xs).sum() / total) + 0.5,
float((weight * ys).sum() / total) + 0.5)
# ---------------------------------------------------------------- 几何
def homography(src, dst):
"""求解 src(4×2) → dst(4×2) 的 3×3 单应矩阵(h8 = 1)。"""
a = np.zeros((8, 8), dtype=np.float64)
b = np.zeros(8, dtype=np.float64)
for i in range(4):
x, y = src[i]
u, v = dst[i]
a[2 * i] = [x, y, 1, 0, 0, 0, -x * u, -y * u]
b[2 * i] = u
a[2 * i + 1] = [0, 0, 0, x, y, 1, -x * v, -y * v]
b[2 * i + 1] = v
h = np.linalg.solve(a, b)
return np.append(h, 1.0).reshape(3, 3)
def project(h, points):
"""单应变换。逐分量展开而非 matmul:大点集下更省内存,
也避开 BLAS 在大矩阵乘法上偶发的伪浮点警告。"""
pts = np.asarray(points, dtype=np.float64)
x = pts[..., 0]
y = pts[..., 1]
u = h[0, 0] * x + h[0, 1] * y + h[0, 2]
v = h[1, 0] * x + h[1, 1] * y + h[1, 2]
w = h[2, 0] * x + h[2, 1] * y + h[2, 2]
# w 趋近 0 表示该点被映射到无穷远(逆映射时落在画面之外),
# 夹住分母避免 inf/nan 污染后续采样。
w = np.where(np.abs(w) < 1e-12, 1e-12, w)
return np.stack([u / w, v / w], axis=-1)
def local_scale(h, x, y):
"""单应矩阵在 (x, y) 处的各向同性放大率:照片像素 / 显示像素。"""
u = h[0, 0] * x + h[0, 1] * y + h[0, 2]
v = h[1, 0] * x + h[1, 1] * y + h[1, 2]
w = h[2, 0] * x + h[2, 1] * y + h[2, 2]
dudx = (h[0, 0] * w - u * h[2, 0]) / w ** 2
dudy = (h[0, 1] * w - u * h[2, 1]) / w ** 2
dvdx = (h[1, 0] * w - v * h[2, 0]) / w ** 2
dvdy = (h[1, 1] * w - v * h[2, 1]) / w ** 2
return float(np.sqrt(abs(dudx * dvdy - dudy * dvdx)))
def bilinear(gray, points):
height, width = gray.shape
x = np.clip(points[..., 0], 0, width - 1.001)
y = np.clip(points[..., 1], 0, height - 1.001)
x0 = np.floor(x).astype(np.int32)
y0 = np.floor(y).astype(np.int32)
fx = x - x0
fy = y - y0
v00 = gray[y0, x0]
v01 = gray[y0, x0 + 1]
v10 = gray[y0 + 1, x0]
v11 = gray[y0 + 1, x0 + 1]
return (v00 * (1 - fx) * (1 - fy) + v01 * fx * (1 - fy) +
v10 * (1 - fx) * fy + v11 * fx * fy)
def box_mean(values, ky, kx):
"""边界收缩的滑动平均,用作局部阈值面。"""
rows, cols = values.shape
ky = max(1, min(ky if ky % 2 == 1 else ky - 1, rows if rows % 2 == 1 else rows - 1))
kx = max(1, min(kx if kx % 2 == 1 else kx - 1, cols if cols % 2 == 1 else cols - 1))
ry, rx = ky // 2, kx // 2
padded = np.pad(values, ((ry, ry), (rx, rx)), mode="edge")
integral = np.zeros((padded.shape[0] + 1, padded.shape[1] + 1), dtype=np.float64)
integral[1:, 1:] = padded.cumsum(axis=0).cumsum(axis=1)
total = (integral[ky:ky + rows, kx:kx + cols]
- integral[0:rows, kx:kx + cols]
- integral[ky:ky + rows, 0:cols]
+ integral[0:rows, 0:cols])
return total / float(ky * kx)
# ---------------------------------------------------------------- 分析
def analyze_band(gray, spec, band, h, threshold_window):
centers = module_centers_active(band, spec)
photo = project(h, centers)
samples = bilinear(gray, photo)
expected = band_bits(band) # 1 = 黑
threshold = box_mean(samples, threshold_window, threshold_window)
decoded = (samples < threshold).astype(np.uint8) # 比阈值暗 → 判为黑(1)
errors = int(np.count_nonzero(decoded != expected))
total = expected.size
ber = errors / float(total)
white = samples[expected == 0]
black = samples[expected == 1]
if white.size and black.size:
mw, mb = float(white.mean()), float(black.mean())
contrast = (mw - mb) / (mw + mb) if (mw + mb) > 0 else 0.0
else:
mw = mb = contrast = 0.0
cx = band.x + band.width_px / 2.0
cy = band.y + band.height_px / 2.0
px_per_module = local_scale(h, cx, cy) * band.pitch_px
return {
"index": band.index,
"pitch_px": band.pitch_px,
"px_per_module": px_per_module,
"modules": total,
"errors": errors,
"ber": ber,
"contrast": contrast,
"white": mw,
"black": mb,
}
def inner_fec_overhead(ber):
"""把给定原始误码率压到可忽略的带错率,所需的内码冗余(粗估)。
条带级 CRC 下,1750 B 的条带只要有 1 bit 错就整条报废,
因此必须用内码(RS/LDPC)先把原始 BER 吃掉,外层喷泉码只负责丢包。
GF(256) 的 RS:字节错率 ≈ 8·BER,留 3 倍余量 → 冗余 ≈ 48·BER。
"""
if ber <= 0:
return 0.0
return min(1.0, 48.0 * ber)
def verdict(ber):
if ber == 0:
return "✅ 无误码"
if ber < 1e-3:
return "✅ 可用"
if ber < 1e-2:
return "⚠️ 勉强"
return "❌ 不可用"
def crossing(rows, limit):
"""在 BER-px/模块 曲线上插值出 BER 恰好等于 limit 的位置。"""
ordered = sorted(rows, key=lambda r: r["px_per_module"])
for a, b in zip(ordered, ordered[1:]):
if a["ber"] > limit >= b["ber"]:
ya, yb = np.log10(max(a["ber"], 1e-9)), np.log10(max(b["ber"], 1e-9))
if abs(yb - ya) < 1e-12:
return b["px_per_module"]
t = (np.log10(limit) - ya) / (yb - ya)
return a["px_per_module"] + t * (b["px_per_module"] - a["px_per_module"])
return None
def write_debug_image(path, gray, spec, h, markers):
from PIL import Image, ImageDraw
image = Image.fromarray(gray.astype(np.uint8)).convert("RGB")
draw = ImageDraw.Draw(image)
for x, y in markers:
draw.ellipse([x - 9, y - 9, x + 9, y + 9], outline=(255, 40, 40), width=3)
corners = project(h, spec.active_corners())
draw.polygon([tuple(p) for p in corners], outline=(40, 220, 255))
for band in spec.bands:
rect = [(band.x, band.y),
(band.x + band.width_px, band.y),
(band.x + band.width_px, band.y + band.height_px),
(band.x, band.y + band.height_px)]
pts = project(h, rect)
draw.polygon([tuple(p) for p in pts], outline=(80, 255, 120))
image.save(path)
def main() -> int:
parser = argparse.ArgumentParser(description="分析楔形标定图照片")
parser.add_argument("--spec", required=True, help="wedge_gen.py 产出的 .json")
parser.add_argument("--photo", required=True, help="手机拍摄的照片")
parser.add_argument("--analysis-width", type=int, default=1920,
help="模拟 ImageAnalysis 流宽度,0 表示不降采样")
parser.add_argument("--threshold-window", type=int, default=17,
help="局部阈值面的窗口边长(模块数)")
parser.add_argument("--debug-image", type=str, default=None,
help="写出一张叠加了定位结果的诊断图")
args = parser.parse_args()
spec = WedgeSpec.load(args.spec)
gray, original = load_gray(args.photo, args.analysis_width)
debug = {}
markers = find_markers(gray, debug)
h = homography(spec.active_corners(), markers)
rows = [analyze_band(gray, spec, band, h, args.threshold_window) for band in spec.bands]
if args.debug_image:
write_debug_image(args.debug_image, gray, spec, h, markers)
width_px = float(np.hypot(markers[1][0] - markers[0][0], markers[1][1] - markers[0][1]))
print("照片:%s" % os.path.basename(args.photo))
print("原始尺寸 %d×%d → 分析尺寸 %d×%d" % (original[0], original[1], gray.shape[1], gray.shape[0]))
print("标定图 active 宽 %d 显示像素 → 照片中 %.1f 像素(放大率 %.3f)"
% (spec.active_w, width_px, width_px / spec.active_w))
print()
print("%-6s %-9s %-11s %-9s %-10s %-11s %s"
% ("条带", "显示pitch", "px/模块", "对比度", "模块数", "误码率", "判定"))
for row in rows:
print("%-6d %-9d %-11.2f %-9.3f %-10d %-11s %s"
% (row["index"], row["pitch_px"], row["px_per_module"], row["contrast"],
row["modules"],
"0" if row["ber"] == 0 else "%.2e" % row["ber"],
verdict(row["ber"])))
print()
limit = crossing(rows, 1e-3)
if limit is not None:
print("BER=1e-3 的临界点:约 %.2f px/模块" % limit)
usable = [r for r in rows if r["ber"] < 1e-3]
if usable:
best = min(usable, key=lambda r: r["px_per_module"])
print("本次实测可用下限:%.2f px/模块(BER %s,内码冗余需 %.1f%%)"
% (best["px_per_module"],
"0" if best["ber"] == 0 else "%.1e" % best["ber"],
inner_fec_overhead(best["ber"]) * 100))
area = gray.shape[0] * gray.shape[1] * 0.95
modules = area / best["px_per_module"] ** 2
payload = modules * (1 - 0.04) * (1 - 0.15 - inner_fec_overhead(best["ber"])) / 8
print("→ 按此下限,%d×%d 分析流每画布净载荷约 %.0f B"
% (gray.shape[1], gray.shape[0], max(payload, 0)))
for fps in (24, 30, 60):
rate = payload * fps * 0.92
if rate > 0:
print(" @%d FPS:%.0f KB/s 1MB %.2fs 10MB %.2fs"
% (fps, rate / 1024, 1048576 / rate, 10485760 / rate))
else:
print("所有条带都超过 1e-3,请靠近屏幕重拍,或改用更大的 --pitches")
return 0
if __name__ == "__main__":
raise SystemExit(main())