Files
agent/skills/document-photo-to-pdf/doc_deskew/auto_quad.py
T
kicer a86b748a6f 重构 document-photo-to-pdf:审核页改为 data.db 驱动并支持一键重生成
run.py 接上 edits/enhance/dpi/status/review,并把运行记录写进会话 data.db;审核页模板移到 skill/web,运行时发布到 .app/doc-review/,页面通过 /api/db 水合并调用通用技能执行接口重生成;移除 make_review.py 与模板注入。
2026-10-23 23:15:52 +08:00

609 lines
20 KiB
Python
Raw 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.
# -*- coding: utf-8 -*-
"""纸张边线检测:从一张已转正的 PIL 图里估四个纸角。
对外只有 detect(img, P) -> (corners, info):
- img 是已做 exif_transpose 的 RGB 图;
- corners 是原图像素坐标 [(x, y)],顺序 左上、右上、右下、左下;
- info 里带覆盖率、纸面占比、回退标记,供上层做置信度告警。
设计要点:
- 不打印、不落盘、不画图。检测失败返回 ([], info),由调用方决定是否终止。
- 纸面掩膜保留两份:腐蚀过的只用于限定边缘搜索环带;回退几何用未腐蚀的
原始掩膜,避免角点系统性内收(旧实现两次 erode 会让角点切进纸内)。
- 回退时不再只用 4 个极值点连线,而是用整条掩膜边界按边拟合,再求交点。
"""
import numpy as np
from PIL import Image
# ---------------------------------------------------------------- 基础工具
def _odd(size):
size = int(size)
if size < 3:
size = 3
if size % 2 == 0:
size += 1
return size
def _slide_reduce(a, k, op, axis):
"""沿 axis 做窗口 k 的滑动 max/min,越界按中性值填充(与 PIL 的边缘复制等价)。
van Herk / Gil-Werman:块内前缀极值 + 块内后缀极值,O(1)/像素。
二维 max/min 可分离,故行列两遍与二维滤波逐像素等价,
但避开了 PIL rankfilter 的 O(k^2)/像素(k=35 时慢 30 倍以上)。
"""
a = np.moveaxis(np.asarray(a, dtype=bool).astype(np.uint8) * 255,
axis, -1)
M, N = a.shape
r = k // 2
n = N + 2 * r
nb = (n + k - 1) // k
m = nb * k
p = np.full((M, m), 0 if op == "max" else 255, dtype=np.uint8)
p[:, r:r + N] = a
blk = p.reshape(M, nb, k)
if op == "max":
fwd = np.maximum.accumulate(blk, axis=-1).reshape(M, m)
bwd = np.maximum.accumulate(blk[:, :, ::-1], axis=-1)[:, :, ::-1]
bwd = bwd.reshape(M, m)
out = np.maximum(bwd[:, :N], fwd[:, k - 1:k - 1 + N])
else:
fwd = np.minimum.accumulate(blk, axis=-1).reshape(M, m)
bwd = np.minimum.accumulate(blk[:, :, ::-1], axis=-1)[:, :, ::-1]
bwd = bwd.reshape(M, m)
out = np.minimum(bwd[:, :N], fwd[:, k - 1:k - 1 + N])
return np.moveaxis(out, -1, axis) > 127
def dilate(mask, size):
k = _odd(size)
return _slide_reduce(_slide_reduce(mask, k, "max", 1), k, "max", 0)
def erode(mask, size):
k = _odd(size)
return _slide_reduce(_slide_reduce(mask, k, "min", 1), k, "min", 0)
def closing(mask, size):
return erode(dilate(mask, size), size)
def opening(mask, size):
return dilate(erode(mask, size), size)
def rgb_to_sv(arr):
maxc = arr.max(axis=-1)
minc = arr.min(axis=-1)
delta = maxc - minc
S = np.zeros_like(maxc, dtype=np.float32)
np.divide(delta, maxc, out=S, where=maxc > 1e-6)
return S.astype(np.float32), maxc.astype(np.float32)
def luminance(arr):
return (0.299 * arr[..., 0] + 0.587 * arr[..., 1]
+ 0.114 * arr[..., 2]).astype(np.float32)
def box_mean(img, r):
"""O(1)/像素的方框均值(积分图),r 为半径。"""
img = np.asarray(img, dtype=np.float32)
H, W = img.shape
pad = np.zeros((H + 1, W + 1), dtype=np.float32)
pad[1:, 1:] = img
ii = pad.cumsum(0).cumsum(1)
ys = np.arange(H)
xs = np.arange(W)
y0 = np.clip(ys - r, 0, H)
y1 = np.clip(ys + r + 1, 0, H)
x0 = np.clip(xs - r, 0, W)
x1 = np.clip(xs + r + 1, 0, W)
# 边界裁剪等价于把积分图向外按边复制 r 行/列,这样四个角全部可用切片取,
# 避开 np.ix_ 花式索引的 4 次全图 gather(快 3 倍以上)。
k = 2 * r + 1
pe = np.pad(ii, ((r, r + 1), (r, r + 1)), mode="edge")
S = (pe[k:k + H, k:k + W] - pe[0:H, k:k + W]
- pe[k:k + H, 0:W] + pe[0:H, 0:W])
cnt = (y1 - y0)[:, None] * (x1 - x0)[None, :]
return S / np.maximum(cnt, 1).astype(np.float32)
def gaussian_blur_np(img, sigma):
radius = int(np.ceil(sigma * 3))
if radius < 1:
return img.astype(np.float32)
x = np.arange(-radius, radius + 1, dtype=np.float32)
k = np.exp(-x * x / (2 * sigma * sigma))
k /= k.sum()
H, W = img.shape
p = np.pad(img, radius, mode="edge")
tmp = np.zeros((H, W), dtype=np.float32)
for i, kv in enumerate(k):
tmp += kv * p[radius:radius + H, i:i + W]
p = np.pad(tmp, ((radius, radius), (0, 0)), mode="edge")
out = np.zeros((H, W), dtype=np.float32)
for i, kv in enumerate(k):
out += kv * p[i:i + H, :]
return out
def convolve3x3(img, kernel):
H, W = img.shape
p = np.pad(img, 1, mode="edge")
out = np.zeros((H, W), dtype=np.float32)
for i in range(3):
for j in range(3):
kv = kernel[i, j]
if kv != 0:
out += kv * p[i:i + H, j:j + W]
return out
def sobel_magnitude(gray):
kx = np.array([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]], dtype=np.float32)
ky = np.array([[-1, -2, -1], [0, 0, 0], [1, 2, 1]], dtype=np.float32)
gx = convolve3x3(gray, kx)
gy = convolve3x3(gray, ky)
return np.sqrt(gx * gx + gy * gy)
# ---------------------------------------------------------------- 连通域 & 填孔
def downsample_any(mask, factor):
if factor <= 1:
return mask
H, W = mask.shape
H2, W2 = H // factor, W // factor
return mask[:H2 * factor, :W2 * factor].reshape(
H2, factor, W2, factor).any(axis=(1, 3))
def upsample_nearest(mask_small, target_h, target_w):
h, w = mask_small.shape
yi = np.linspace(0, h - 1, target_h).astype(np.int32)
xi = np.linspace(0, w - 1, target_w).astype(np.int32)
return mask_small[np.ix_(yi, xi)]
def _row_runs(mask):
"""把二值掩膜拆成每行的连续段,返回 (row, start, end),end 不含。"""
H, W = mask.shape
pm = np.zeros((H, W + 2), dtype=np.int8)
pm[:, 1:-1] = mask
d = np.diff(pm, axis=1)
ry, rs = np.nonzero(d == 1)
_, re_ = np.nonzero(d == -1)
return ry, rs, re_
def _run_labels(ry, rs, re_, H, eight):
"""行程级并查集:4/8 邻接,返回每个行程的连通分量标号。"""
n = len(ry)
parent = np.arange(n)
def find(a):
while parent[a] != a:
parent[a] = parent[parent[a]]
a = parent[a]
return a
row_start = np.searchsorted(ry, np.arange(H + 1))
for y in range(H - 1):
a0, a1 = row_start[y], row_start[y + 1]
b0, b1 = row_start[y + 1], row_start[y + 2]
i, j = a0, b0
while i < a1 and j < b1:
s1, e1 = rs[i], re_[i]
s2, e2 = rs[j], re_[j]
hit = (s2 <= e1 and s1 <= e2) if eight else (s2 < e1 and s1 < e2)
if hit:
ra, rb = find(i), find(j)
if ra != rb:
parent[rb] = ra
if e1 <= e2:
i += 1
else:
j += 1
return np.array([find(i) for i in range(n)], dtype=np.int64)
def fill_holes(mask_small):
"""填掉不与画面边界连通的背景(4 邻接),行程 + 并查集实现。"""
m = np.asarray(mask_small, dtype=bool)
H, W = m.shape
bg = ~m
if not bg.any():
return m.copy()
ry, rs, re_ = _row_runs(bg)
if len(ry) == 0:
return m.copy()
lab = _run_labels(ry, rs, re_, H, eight=False)
touch = (ry == 0) | (ry == H - 1) | (rs == 0) | (re_ >= W)
nlab = int(lab.max()) + 1
edge = np.zeros(nlab, dtype=bool)
np.logical_or.at(edge, lab, touch)
sel = ~edge[lab]
out = m.copy()
for y, s, e in zip(ry[sel], rs[sel], re_[sel]):
out[y, s:e] = True
return out
def largest_connected(mask_small):
"""取最大 8 邻接连通域(行程 + 并查集,逐像素计数)。"""
m = np.asarray(mask_small, dtype=bool)
H, W = m.shape
if not m.any():
return np.zeros_like(m)
ry, rs, re_ = _row_runs(m)
lab = _run_labels(ry, rs, re_, H, eight=True)
w = (re_ - rs).astype(np.int64)
nlab = int(lab.max()) + 1
size = np.bincount(lab, weights=w, minlength=nlab)
best = int(np.argmax(size))
sel = lab == best
out = np.zeros((H, W), dtype=bool)
for y, s, e in zip(ry[sel], rs[sel], re_[sel]):
out[y, s:e] = True
return out
# ---------------------------------------------------------------- 纸面掩膜
def otsu_threshold(score):
hist, bin_edges = np.histogram(score, bins=256, range=(0.0, 1.0))
hist = hist.astype(np.float64)
total = hist.sum()
if total <= 0:
return 0.5
p = hist / total
centers = (bin_edges[:-1] + bin_edges[1:]) * 0.5
w0 = np.cumsum(p)
w1 = 1.0 - w0
m0 = np.cumsum(p * centers)
mt = m0[-1]
with np.errstate(divide="ignore", invalid="ignore"):
mu0 = m0 / np.maximum(w0, 1e-12)
mu1 = (mt - m0) / np.maximum(w1, 1e-12)
between = w0 * w1 * (mu0 - mu1) ** 2
between = np.nan_to_num(between, nan=-1.0)
return float(centers[int(np.argmax(between))])
def paper_masks(arr, P):
"""返回 (raw, eroded)。
raw:未腐蚀的纸面掩膜,用于回退几何,避免角点内收。
eroded:腐蚀后的掩膜,只用于限定边缘搜索环带。
"""
d = P["detect"]
H, W = arr.shape[:2]
S, V = rgb_to_sv(arr)
score = (V * (1.0 - S)).astype(np.float32)
th = max(otsu_threshold(score), d["paper_otsu_floor"])
bright = (score > th) & (V > d["paper_v_min"]) & (S < d["paper_s_max"])
factor = max(1, min(H, W) // d["paper_mask_factor_div"])
bs = downsample_any(bright, factor)
m = closing(bs, _odd(max(d["paper_close_min"],
min(bs.shape) // d["paper_close_div"])))
m = fill_holes(m)
m = largest_connected(m)
m = closing(m, _odd(max(d["paper_close_min"],
min(bs.shape) // d["paper_close2_div"])))
m = fill_holes(m)
raw_small = m
eroded_small = erode(m, _odd(d["mask_erode_kernel"]))
if factor > 1:
raw = upsample_nearest(raw_small, H, W)
eroded = upsample_nearest(eroded_small, H, W)
else:
raw, eroded = raw_small, eroded_small
return raw, eroded
# ---------------------------------------------------------------- 边缘图
def boundary_band(paper, k):
k = _odd(k)
return dilate(paper, k) & ~erode(paper, k)
def edge_map(arr, P):
d = P["detect"]
H = arr.shape[0]
gray = luminance(arr)
sigma = max(1.0, H / float(d["edge_sigma_div"]))
blurred = gaussian_blur_np(gray, sigma)
mag = sobel_magnitude(blurred)
local = box_mean(mag, max(3, H // d["edge_box_div"]))
th = np.maximum(d["edge_low"], local * d["edge_local_gain"])
return mag > th
def boundary_step_filter(arr, paper, P):
"""跨纸边亮度阶跃:比较掩膜内侧/外侧小窗的 V 均值。
纸边是真实的明暗台阶,木纹/阴影纹理阶跃小。两级窗口:掩膜准确处用
r_small,掩膜略有偏移处依靠 r_big 补上。
"""
d = P["detect"]
_, V = rgb_to_sv(arr)
p = paper.astype(np.float32)
q = 1.0 - p
def side_means(r):
din = box_mean(p, r)
dout = box_mean(q, r)
vin = box_mean(V * p, r) / np.maximum(din, 1e-6)
vout = box_mean(V * q, r) / np.maximum(dout, 1e-6)
ok = (din > 0.08) & (dout > 0.08)
return np.where(ok, np.abs(vin - vout), 0.0)
step = np.maximum(side_means(d["step_r_small"]),
side_means(d["step_r_big"]))
return step > d["step_th"]
# ---------------------------------------------------------------- 四角提取
def mask_boundary_points(mask, P):
"""掩膜边界像素坐标 (N, 2),顺序 (x, y)。"""
inner = erode(mask, _odd(P["detect"]["mask_erode_kernel"]))
ys, xs = np.where(mask & ~inner)
if len(xs) == 0:
return np.zeros((0, 2), dtype=np.float32)
return np.stack([xs, ys], axis=1).astype(np.float32)
def _fit_line(pts):
"""总体最小二乘拟直线,返回法向量 n 与 n·p = c。"""
c0 = pts.mean(axis=0)
q = pts - c0
cov = (q.T @ q) / max(len(pts) - 1, 1)
w, v = np.linalg.eigh(cov)
direction = v[:, int(np.argmax(w))]
n = np.array([-direction[1], direction[0]], dtype=np.float64)
nn = np.linalg.norm(n)
if nn < 1e-9:
return np.array([0.0, 1.0]), float(c0[1])
n = n / nn
return n, float(n @ c0)
def _robust_fit(pts, robust_px):
n, c = _fit_line(pts)
sel = pts
for _ in range(2):
res = np.abs(sel @ n - c)
keep = sel[res <= max(robust_px, 1.0) * 2.5]
if len(keep) < 40:
break
n, c = _fit_line(keep)
sel = keep
return n, c
def _intersect(n1, c1, n2, c2):
A = np.vstack([n1, n2])
b = np.array([c1, c2], dtype=np.float64)
try:
return np.linalg.solve(A, b)
except np.linalg.LinAlgError:
return None
def _side_line(p0, p1):
dv = np.asarray(p1, dtype=np.float64) - np.asarray(p0, dtype=np.float64)
L = float(np.linalg.norm(dv))
if L < 1e-6:
return None
u = dv / L
n = np.array([-u[1], u[0]], dtype=np.float64)
return n, float(n @ np.asarray(p0, dtype=np.float64)), u, L
def detect_quad_corners(paper_raw, points, P):
"""从掩膜边界 + 边缘点估四角,返回 (corners, fallback_sides)。"""
d = P["detect"]
base = mask_boundary_points(paper_raw, P)
if len(base) < 40:
return [], [0, 1, 2, 3]
bx, by = base[:, 0], base[:, 1]
anchors = np.array([
base[int(np.argmin(bx + by))], # 左上
base[int(np.argmax(bx - by))], # 右上
base[int(np.argmax(bx + by))], # 右下
base[int(np.argmin(bx - by))], # 左下
], dtype=np.float64)
init = [_side_line(anchors[i], anchors[(i + 1) % 4]) for i in range(4)]
# 用整条掩膜边界重拟合每一边(排除两端,避开角点圆角)
base_lines = []
for i in range(4):
sl = init[i]
if sl is None:
base_lines.append(None)
continue
n, c, u, L = sl
p0 = anchors[i]
dist = np.abs(base @ n - c)
proj = (base - p0) @ u
m = d["boundary_side_margin"]
sel = base[(dist <= d["group_tol_px"]) &
(proj >= L * m) & (proj <= L * (1.0 - m))]
if len(sel) >= 40:
n2, c2 = _robust_fit(sel, d["robust_px"])
base_lines.append((n2, c2))
else:
base_lines.append((n, c))
final_lines = list(base_lines)
fallback_sides = [0, 1, 2, 3]
if points is not None and len(points) >= d["min_edge_points"]:
pts = np.asarray(points, dtype=np.float64)
dists = []
for line in base_lines:
if line is None:
dists.append(np.full(len(pts), 1e9))
else:
dists.append(np.abs(pts @ line[0] - line[1]))
D = np.stack(dists, axis=1)
idx = np.argmin(D, axis=1)
dmin = D[np.arange(len(pts)), idx]
fallback_sides = []
for i in range(4):
line = base_lines[i]
if line is None:
fallback_sides.append(i)
continue
sel = pts[(idx == i) & (dmin <= d["group_tol_px"])]
sl = init[i]
if sl is not None:
u, L = sl[2], sl[3]
p0 = anchors[i]
m = d["boundary_side_margin"]
proj = (sel - p0) @ u
sel = sel[(proj >= L * m) & (proj <= L * (1.0 - m))]
if len(sel) >= d["min_edge_points"]:
n2, c2 = _robust_fit(sel, d["robust_px"])
final_lines[i] = (n2, c2)
else:
fallback_sides.append(i)
H, W = paper_raw.shape
oob = d["corner_oob_frac"]
out = []
for i in range(4):
chosen = None
for lines in (final_lines, base_lines):
l1, l2 = lines[i - 1], lines[i]
if l1 is None or l2 is None:
continue
det = l1[0][0] * l2[0][1] - l2[0][0] * l1[0][1]
if abs(det) < 1e-3:
continue
p = _intersect(l1[0], l1[1], l2[0], l2[1])
if p is None:
continue
if (-oob * W <= p[0] <= (1.0 + oob) * W and
-oob * H <= p[1] <= (1.0 + oob) * H):
chosen = (float(p[0]), float(p[1]))
break
if chosen is None:
chosen = (float(anchors[i][0]), float(anchors[i][1]))
if i not in fallback_sides:
fallback_sides.append(i)
out.append(chosen)
return out, sorted(set(fallback_sides))
# ---------------------------------------------------------------- 覆盖率
def border_coverage_exact(edges, paper, tol):
"""沿掩膜逐行/逐列的真实边界测边缘覆盖率。"""
H, W = paper.shape
col_has = paper.any(axis=0)
row_has = paper.any(axis=1)
top_hit = top_n = 0
bot_hit = bot_n = 0
for x in np.where(col_has)[0]:
ys = np.where(paper[:, x])[0]
y0, y1 = ys.min(), ys.max()
if edges[max(0, y0 - tol):min(H, y0 + tol + 1), x].any():
top_hit += 1
top_n += 1
if edges[max(0, y1 - tol):min(H, y1 + tol + 1), x].any():
bot_hit += 1
bot_n += 1
left_hit = left_n = 0
right_hit = right_n = 0
for y in np.where(row_has)[0]:
xs = np.where(paper[y, :])[0]
x0, x1 = xs.min(), xs.max()
if edges[y, max(0, x0 - tol):min(W, x0 + tol + 1)].any():
left_hit += 1
left_n += 1
if edges[y, max(0, x1 - tol):min(W, x1 + tol + 1)].any():
right_hit += 1
right_n += 1
return {
"top": top_hit / max(top_n, 1),
"bottom": bot_hit / max(bot_n, 1),
"left": left_hit / max(left_n, 1),
"right": right_hit / max(right_n, 1),
}
# ---------------------------------------------------------------- 对外接口
def detect(img, P):
"""检测纸张四角,返回 (corners_原图坐标, info)。失败返回 ([], info)。"""
d = P["detect"]
src_w, src_h = img.size
scale = min(1.0, d["max_side"] / float(max(src_w, src_h)))
if scale < 1.0:
pil = img.resize((int(round(src_w * scale)), int(round(src_h * scale))),
Image.LANCZOS)
else:
pil = img
arr = np.asarray(pil).astype(np.float32) / 255.0
H, W = arr.shape[:2]
paper_raw, paper_eroded = paper_masks(arr, P)
frac = float(paper_raw.sum()) / float(H * W)
info = {
"source_size": [int(src_w), int(src_h)],
"processed_size": [int(W), int(H)],
"scale": round(scale, 6),
"paper_frac": round(frac, 4),
"edge_pixels": 0,
"coverage": {},
"fallback": True,
"fallback_sides": [0, 1, 2, 3],
}
if frac < 0.005 or not paper_raw.any():
return [], info
band = boundary_band(paper_eroded,
_odd(max(d["band_min"], H // d["band_div"])))
edges = edge_map(arr, P)
step = boundary_step_filter(arr, paper_eroded, P)
cand = closing(edges & band & step,
_odd(max(d["cand_close_min"], H // d["cand_close_div"])))
cand = opening(cand,
_odd(max(d["cand_open_min"], H // d["cand_open_div"])))
ey, ex = np.nonzero(cand)
pts = (np.stack([ex, ey], axis=1).astype(np.float32)
if len(ex) >= d["min_edge_points"] else None)
corners, fallback_sides = detect_quad_corners(paper_raw, pts, P)
info["edge_pixels"] = int(cand.sum())
info["fallback_sides"] = fallback_sides
info["fallback"] = bool(fallback_sides)
if not corners:
return [], info
info["coverage"] = {
k: float(v) for k, v in border_coverage_exact(
cand, paper_eroded,
tol=max(d["coverage_tol_min"], H // d["coverage_tol_div"])).items()
}
src_pts = [(float(x / scale), float(y / scale)) for x, y in corners]
return src_pts, info