433 lines
18 KiB
Python
433 lines
18 KiB
Python
#!/usr/bin/env python3
|
||
"""审查 insight-diagram 生成的 SVG 图，做几何校验。
|
||
|
||
检查项（对应三条要求）：
|
||
1. 箭头两端是否落在框图边缘线上 —— 既不"深入"框内，也不"空接"悬空。
|
||
2. 非嵌套框图之间是否重叠。
|
||
3. 框图之间是否留出足够间距。
|
||
|
||
用法:
|
||
python3 review_svg.py docs/architecture.html [more.html ...]
|
||
python3 review_svg.py docs/*.html --min-gap 8 --json
|
||
|
||
退出码: 发现 ERROR 时为 1；仅 WARNING（或干净）为 0；加 --strict 让 WARNING 也返回 1。
|
||
|
||
实现说明：用 html.parser（而非 XML 解析器）遍历，以兼容 SVG-in-HTML 中
|
||
未转义的 & 或文本里的 <<include>> 等；箭头端点允许落在任意图形边缘、
|
||
任意连线/生命线上（汇合点），故序列图/通信图等不会误报"空接"。
|
||
"""
|
||
import argparse
|
||
import json
|
||
import math
|
||
import re
|
||
import sys
|
||
from html.parser import HTMLParser
|
||
|
||
# ---- 几何容差（像素）----
|
||
BOUNDARY_TOL = 6.0 # 端点距图形边 <= 此值视为"落在边上"，正常
|
||
PENETRATION = 8.0 # 端点在框内且距最近边 > 此值视为"深入"（ERROR）
|
||
FLOATING = 8.0 # 端点距所有图形 > 此值且不接任何连线 → "空接"（WARNING）
|
||
JUNCTION_TOL = 6.0 # 端点距其他连线/生命线 <= 此值视为合法汇合点
|
||
OVERLAP_EPS = 2.0 # 两方向交叠都 > 此值才算重叠
|
||
CONTAIN_MARGIN = 2.0 # 判定包含时允许内框略微超出
|
||
SAME_BOX_TOL = 3.0 # 各边相差 <= 此值视为同一个框（去重）
|
||
|
||
# 只有 w/h 同时达到阈值的图形才算"框图节点"，参与重叠/间距校验；
|
||
# 更小的（标签底衬、终止圆点、图例色块）仅作为箭头落点目标。
|
||
MIN_BOX_W = 36.0
|
||
MIN_BOX_H = 22.0
|
||
|
||
# 这些子树内的图形只是装饰/定义，不收集
|
||
SKIP_SUBTREES = {'defs', 'marker', 'pattern', 'clippath', 'lineargradient',
|
||
'radialgradient', 'symbol', 'mask'}
|
||
|
||
|
||
# =====================================================================
|
||
# 基础工具
|
||
# =====================================================================
|
||
def _floats(s):
|
||
return [float(x) for x in re.findall(r'-?\d+(?:\.\d+)?', s or '')]
|
||
|
||
|
||
def _num(v):
|
||
"""解析 SVG 数值属性；含 '%' 或无法解析时返回 None。"""
|
||
if v is None or '%' in v:
|
||
return None
|
||
m = re.match(r'\s*(-?\d+(?:\.\d+)?)', v)
|
||
return float(m.group(1)) if m else None
|
||
|
||
|
||
def _parse_translate(transform):
|
||
"""累加 transform 中的 translate 偏移，返回 (dx, dy)。"""
|
||
dx = dy = 0.0
|
||
for m in re.finditer(r'translate\(\s*([-\d.]+)[\s,]*([-\d.]+)?\s*\)', transform or ''):
|
||
dx += float(m.group(1))
|
||
dy += float(m.group(2)) if m.group(2) is not None else 0.0
|
||
return dx, dy
|
||
|
||
|
||
def _point_seg_dist(px, py, ax, ay, bx, by):
|
||
"""点到线段的最短距离。"""
|
||
dx, dy = bx - ax, by - ay
|
||
if dx == 0 and dy == 0:
|
||
return math.hypot(px - ax, py - ay)
|
||
t = ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)
|
||
t = max(0.0, min(1.0, t))
|
||
return math.hypot(px - (ax + t * dx), py - (ay + t * dy))
|
||
|
||
|
||
def parse_path_points(d):
|
||
"""提取 path 各命令的落点（曲线只取终点），用于求首/末锚点。"""
|
||
pts = []
|
||
cx = cy = 0.0
|
||
cmd, nums = None, []
|
||
tokens = re.findall(r'([MmLlHhVvCcSsQqTtAaZz])|(-?\d+(?:\.\d+)?)', d or '')
|
||
|
||
def flush():
|
||
nonlocal cx, cy
|
||
if cmd in ('M', 'L', 'T'):
|
||
for i in range(0, len(nums) - 1, 2):
|
||
cx, cy = nums[i], nums[i + 1]; pts.append((cx, cy))
|
||
elif cmd in ('m', 'l', 't'):
|
||
for i in range(0, len(nums) - 1, 2):
|
||
cx, cy = cx + nums[i], cy + nums[i + 1]; pts.append((cx, cy))
|
||
elif cmd == 'H':
|
||
for v in nums: cx = v; pts.append((cx, cy))
|
||
elif cmd == 'h':
|
||
for v in nums: cx += v; pts.append((cx, cy))
|
||
elif cmd == 'V':
|
||
for v in nums: cy = v; pts.append((cx, cy))
|
||
elif cmd == 'v':
|
||
for v in nums: cy += v; pts.append((cx, cy))
|
||
elif cmd in ('C', 'S', 'Q') and len(nums) >= 2:
|
||
cx, cy = nums[-2], nums[-1]; pts.append((cx, cy))
|
||
elif cmd in ('c', 's', 'q') and len(nums) >= 2:
|
||
cx, cy = cx + nums[-2], cy + nums[-1]; pts.append((cx, cy))
|
||
for tok_cmd, tok_num in tokens:
|
||
if tok_cmd:
|
||
if cmd is not None:
|
||
flush()
|
||
cmd, nums = tok_cmd, []
|
||
else:
|
||
nums.append(float(tok_num))
|
||
if cmd is not None:
|
||
flush()
|
||
return pts
|
||
|
||
|
||
# =====================================================================
|
||
# 图形对象
|
||
# =====================================================================
|
||
class Shape:
|
||
"""任意几何图形的统一表示，用 bbox + 类型描述。"""
|
||
__slots__ = ('kind', 'x0', 'y0', 'x1', 'y1', 'cx', 'cy', 'rx', 'ry')
|
||
|
||
def __init__(self, kind, x0, y0, x1, y1):
|
||
self.kind = kind
|
||
self.x0, self.y0, self.x1, self.y1 = x0, y0, x1, y1
|
||
self.cx, self.cy = (x0 + x1) / 2, (y0 + y1) / 2
|
||
self.rx, self.ry = (x1 - x0) / 2, (y1 - y0) / 2
|
||
|
||
@property
|
||
def w(self): return self.x1 - self.x0
|
||
@property
|
||
def h(self): return self.y1 - self.y0
|
||
|
||
def is_box(self):
|
||
return self.w >= MIN_BOX_W and self.h >= MIN_BOX_H
|
||
|
||
def signed_dist(self, px, py):
|
||
"""点到边界的有符号距离：内部为负、外部为正、≈0 在边上。"""
|
||
if self.kind == 'ellipse' and self.rx > 0 and self.ry > 0:
|
||
nx, ny = (px - self.cx) / self.rx, (py - self.cy) / self.ry
|
||
return (math.hypot(nx, ny) - 1.0) * ((self.rx + self.ry) / 2.0)
|
||
if self.kind == 'circle' and self.rx > 0:
|
||
return math.hypot(px - self.cx, py - self.cy) - self.rx
|
||
dx = max(self.x0 - px, 0, px - self.x1)
|
||
dy = max(self.y0 - py, 0, py - self.y1)
|
||
if dx > 0 or dy > 0:
|
||
return math.hypot(dx, dy)
|
||
return -min(px - self.x0, self.x1 - px, py - self.y0, self.y1 - py)
|
||
|
||
def bbox_key(self):
|
||
return (round(self.x0, 1), round(self.y0, 1),
|
||
round(self.x1, 1), round(self.y1, 1))
|
||
|
||
|
||
def _contains(a, b):
|
||
"""框 a 是否（在容差内）包含框 b 且二者不等大。"""
|
||
return (b.x0 >= a.x0 - CONTAIN_MARGIN and b.x1 <= a.x1 + CONTAIN_MARGIN and
|
||
b.y0 >= a.y0 - CONTAIN_MARGIN and b.y1 <= a.y1 + CONTAIN_MARGIN and
|
||
not (abs(a.x0 - b.x0) < SAME_BOX_TOL and abs(a.x1 - b.x1) < SAME_BOX_TOL and
|
||
abs(a.y0 - b.y0) < SAME_BOX_TOL and abs(a.y1 - b.y1) < SAME_BOX_TOL))
|
||
|
||
|
||
# =====================================================================
|
||
# 用 HTMLParser 遍历 SVG（容忍未转义字符）
|
||
# =====================================================================
|
||
class SvgCollector(HTMLParser):
|
||
def __init__(self):
|
||
super().__init__(convert_charrefs=True)
|
||
self.stack = [{'ox': 0.0, 'oy': 0.0, 'skip': False}]
|
||
self.shapes = [] # 所有图形（含小图形），用于箭头落点目标
|
||
self.connectors = [] # 带 marker 的 line/path
|
||
self.segments = [] # 所有 line/path 折线段，用于汇合点判定
|
||
|
||
# void/自闭合元素
|
||
def handle_startendtag(self, tag, attrs):
|
||
self._emit(tag.lower(), dict(attrs))
|
||
|
||
def handle_starttag(self, tag, attrs):
|
||
tag = tag.lower()
|
||
a = dict(attrs)
|
||
parent = self.stack[-1]
|
||
dx, dy = _parse_translate(a.get('transform', ''))
|
||
node = {'ox': parent['ox'] + dx, 'oy': parent['oy'] + dy,
|
||
'skip': parent['skip'] or tag in SKIP_SUBTREES}
|
||
self.stack.append(node)
|
||
self._emit(tag, a, ctx=node)
|
||
|
||
def handle_endtag(self, tag):
|
||
if len(self.stack) > 1:
|
||
self.stack.pop()
|
||
|
||
def _emit(self, tag, a, ctx=None):
|
||
ctx = ctx or self.stack[-1]
|
||
if ctx['skip'] or tag in SKIP_SUBTREES:
|
||
return
|
||
ox, oy = ctx['ox'], ctx['oy']
|
||
dx, dy = _parse_translate(a.get('transform', '')) # 自闭合元素自身的 translate
|
||
if tag in ('rect', 'ellipse', 'circle', 'polygon'):
|
||
ox, oy = ox + dx, oy + dy
|
||
|
||
if tag == 'rect':
|
||
x, y = _num(a.get('x', '0')), _num(a.get('y', '0'))
|
||
w, h = _num(a.get('width')), _num(a.get('height'))
|
||
if None not in (x, y, w, h):
|
||
self.shapes.append(Shape('rect', ox + x, oy + y, ox + x + w, oy + y + h))
|
||
elif tag == 'ellipse':
|
||
cx, cy = _num(a.get('cx', '0')), _num(a.get('cy', '0'))
|
||
rx, ry = _num(a.get('rx')), _num(a.get('ry'))
|
||
if None not in (cx, cy, rx, ry):
|
||
self.shapes.append(Shape('ellipse', ox + cx - rx, oy + cy - ry,
|
||
ox + cx + rx, oy + cy + ry))
|
||
elif tag == 'circle':
|
||
cx, cy = _num(a.get('cx', '0')), _num(a.get('cy', '0'))
|
||
r = _num(a.get('r'))
|
||
if None not in (cx, cy, r):
|
||
self.shapes.append(Shape('circle', ox + cx - r, oy + cy - r,
|
||
ox + cx + r, oy + cy + r))
|
||
elif tag == 'polygon':
|
||
nums = _floats(a.get('points', ''))
|
||
pts = list(zip(nums[0::2], nums[1::2]))
|
||
if len(pts) >= 3:
|
||
xs = [ox + p[0] for p in pts]; ys = [oy + p[1] for p in pts]
|
||
self.shapes.append(Shape('polygon', min(xs), min(ys), max(xs), max(ys)))
|
||
elif tag == 'line':
|
||
x1, y1 = _num(a.get('x1', '0')), _num(a.get('y1', '0'))
|
||
x2, y2 = _num(a.get('x2', '0')), _num(a.get('y2', '0'))
|
||
if None not in (x1, y1, x2, y2):
|
||
seg = [(ox + x1, oy + y1), (ox + x2, oy + y2)]
|
||
self.segments.append(seg)
|
||
if a.get('marker-end') or a.get('marker-start'):
|
||
self.connectors.append({
|
||
'a': seg[0], 'b': seg[-1], 'seg': seg,
|
||
'arrow_a': bool(a.get('marker-start')),
|
||
'arrow_b': bool(a.get('marker-end'))})
|
||
elif tag == 'path':
|
||
pts = [(ox + px, oy + py) for px, py in parse_path_points(a.get('d', ''))]
|
||
if len(pts) >= 2:
|
||
self.segments.append(pts)
|
||
if a.get('marker-end') or a.get('marker-start'):
|
||
self.connectors.append({
|
||
'a': pts[0], 'b': pts[-1], 'seg': pts,
|
||
'arrow_a': bool(a.get('marker-start')),
|
||
'arrow_b': bool(a.get('marker-end'))})
|
||
|
||
|
||
def collect(svg_text):
|
||
"""返回 (boxes, all_shapes, connectors, segments)。"""
|
||
p = SvgCollector()
|
||
p.feed(svg_text)
|
||
# 框去重（描边 + 遮罩底衬常画两层完全重合的 rect）
|
||
seen, boxes = set(), []
|
||
for s in p.shapes:
|
||
if s.is_box():
|
||
k = s.bbox_key()
|
||
if k not in seen:
|
||
seen.add(k)
|
||
boxes.append(s)
|
||
return boxes, p.shapes, p.connectors, p.segments
|
||
|
||
|
||
def extract_svg(text):
|
||
m = re.search(r'<svg\b.*?</svg>', text, re.DOTALL | re.IGNORECASE)
|
||
return m.group(0) if m else None
|
||
|
||
|
||
# =====================================================================
|
||
# 三项检查
|
||
# =====================================================================
|
||
def check_arrow_endpoints(shapes, connectors, segments):
|
||
"""检查 1：箭头端点应恰好落在某图形边缘，或合法汇入另一连线。
|
||
|
||
会先剔除"装饰性"连线：两端都既不贴任何图形边、也不汇入其它线段
|
||
（典型如图例 Legend 里的示例箭头 / 独立标注线），不参与判定。
|
||
"""
|
||
issues = []
|
||
|
||
def status(px, py):
|
||
dists = [s.signed_dist(px, py) for s in shapes]
|
||
on_edge = bool(dists) and any(abs(d) <= BOUNDARY_TOL for d in dists)
|
||
deepest = min(dists) if dists else 0.0
|
||
nearest_out = min((d for d in dists if d >= 0), default=None)
|
||
return on_edge, deepest, nearest_out
|
||
|
||
for i, c in enumerate(connectors):
|
||
sa = status(*c['a'])
|
||
sb = status(*c['b'])
|
||
a_anchored = sa[0] or _near_other_segment(*c['a'], segments, c['seg'])
|
||
b_anchored = sb[0] or _near_other_segment(*c['b'], segments, c['seg'])
|
||
# 两端都不锚定 → 视为图例/装饰线，跳过
|
||
if not a_anchored and not b_anchored:
|
||
continue
|
||
|
||
ends = []
|
||
if c['arrow_b']:
|
||
ends.append(('终点', c['b'], sb))
|
||
if c['arrow_a']:
|
||
ends.append(('起点', c['a'], sa))
|
||
for label, (px, py), (on_edge, deepest, nearest_out) in ends:
|
||
if on_edge:
|
||
continue # 落在某图形边上：正常
|
||
if deepest < -PENETRATION:
|
||
issues.append(('ERROR',
|
||
f'连线#{i+1} {label}({px:.0f},{py:.0f}) 深入框内 '
|
||
f'{-deepest:.0f}px，应止于框边缘'))
|
||
continue
|
||
if nearest_out is not None and nearest_out > FLOATING:
|
||
if _near_other_segment(px, py, segments, c['seg']):
|
||
continue # 汇入另一连线/生命线
|
||
issues.append(('WARNING',
|
||
f'连线#{i+1} {label}({px:.0f},{py:.0f}) 悬空，'
|
||
f'距最近框边 {nearest_out:.0f}px（空接）'))
|
||
return issues
|
||
|
||
|
||
def _near_other_segment(px, py, segments, own):
|
||
for seg in segments:
|
||
if seg is own:
|
||
continue
|
||
for k in range(len(seg) - 1):
|
||
if _point_seg_dist(px, py, *seg[k], *seg[k + 1]) <= JUNCTION_TOL:
|
||
return True
|
||
return False
|
||
|
||
|
||
def check_overlap(boxes):
|
||
"""检查 2：非嵌套框之间不得重叠。"""
|
||
issues = []
|
||
for i in range(len(boxes)):
|
||
for j in range(i + 1, len(boxes)):
|
||
a, b = boxes[i], boxes[j]
|
||
if _contains(a, b) or _contains(b, a):
|
||
continue
|
||
ox = min(a.x1, b.x1) - max(a.x0, b.x0)
|
||
oy = min(a.y1, b.y1) - max(a.y0, b.y0)
|
||
if ox > OVERLAP_EPS and oy > OVERLAP_EPS:
|
||
issues.append(('ERROR',
|
||
f'框[{a.x0:.0f},{a.y0:.0f} {a.w:.0f}x{a.h:.0f}] 与 '
|
||
f'[{b.x0:.0f},{b.y0:.0f} {b.w:.0f}x{b.h:.0f}] '
|
||
f'重叠 {ox:.0f}x{oy:.0f}px'))
|
||
return issues
|
||
|
||
|
||
def check_spacing(boxes, min_gap):
|
||
"""检查 3：投影相邻、不嵌套、不重叠的框，净间距需 >= min_gap。"""
|
||
issues = []
|
||
for i in range(len(boxes)):
|
||
for j in range(i + 1, len(boxes)):
|
||
a, b = boxes[i], boxes[j]
|
||
if _contains(a, b) or _contains(b, a):
|
||
continue
|
||
xo = min(a.x1, b.x1) - max(a.x0, b.x0)
|
||
yo = min(a.y1, b.y1) - max(a.y0, b.y0)
|
||
if xo > OVERLAP_EPS and yo > OVERLAP_EPS:
|
||
continue # 重叠交给 check_overlap
|
||
gap, axis = None, ''
|
||
if xo > OVERLAP_EPS:
|
||
gap, axis = max(a.y0, b.y0) - min(a.y1, b.y1), '垂直'
|
||
elif yo > OVERLAP_EPS:
|
||
gap, axis = max(a.x0, b.x0) - min(a.x1, b.x1), '水平'
|
||
if gap is not None and 0 <= gap < min_gap:
|
||
issues.append(('WARNING',
|
||
f'框[{a.x0:.0f},{a.y0:.0f}] 与 [{b.x0:.0f},{b.y0:.0f}] '
|
||
f'{axis}间距仅 {gap:.0f}px (< {min_gap:.0f}px)'))
|
||
return issues
|
||
|
||
|
||
def review_file(path, min_gap):
|
||
try:
|
||
with open(path, encoding='utf-8') as f:
|
||
text = f.read()
|
||
except OSError as e:
|
||
return {'file': path, 'issues': [('ERROR', f'无法读取: {e}')],
|
||
'boxes': 0, 'connectors': 0}
|
||
svg = extract_svg(text)
|
||
if not svg:
|
||
return {'file': path, 'issues': [('ERROR', '未找到 <svg> 块')],
|
||
'boxes': 0, 'connectors': 0}
|
||
boxes, shapes, connectors, segments = collect(svg)
|
||
issues = (check_arrow_endpoints(shapes, connectors, segments)
|
||
+ check_overlap(boxes)
|
||
+ check_spacing(boxes, min_gap))
|
||
return {'file': path, 'issues': issues,
|
||
'boxes': len(boxes), 'connectors': len(connectors)}
|
||
|
||
|
||
# =====================================================================
|
||
# CLI
|
||
# =====================================================================
|
||
def main(argv=None):
|
||
ap = argparse.ArgumentParser(
|
||
description='审查 insight-diagram 生成的 SVG（箭头落点 / 框重叠 / 框间距）')
|
||
ap.add_argument('files', nargs='+', help='待检查的 HTML/SVG 文件')
|
||
ap.add_argument('--min-gap', type=float, default=8.0,
|
||
help='相邻框最小净间距阈值 px，默认 8')
|
||
ap.add_argument('--json', action='store_true', help='以 JSON 输出')
|
||
ap.add_argument('--strict', action='store_true',
|
||
help='存在 WARNING 时也以非零码退出')
|
||
args = ap.parse_args(argv)
|
||
|
||
results = [review_file(p, args.min_gap) for p in args.files]
|
||
|
||
if args.json:
|
||
print(json.dumps([
|
||
{'file': r['file'], 'boxes': r['boxes'], 'connectors': r['connectors'],
|
||
'issues': [{'level': lv, 'message': m} for lv, m in r['issues']]}
|
||
for r in results], ensure_ascii=False, indent=2))
|
||
else:
|
||
for r in results:
|
||
errs = [m for lv, m in r['issues'] if lv == 'ERROR']
|
||
warns = [m for lv, m in r['issues'] if lv == 'WARNING']
|
||
mark = '✗' if errs else ('⚠' if warns else '✓')
|
||
print(f'\n{mark} {r["file"]} '
|
||
f'({r["boxes"]} 框 / {r["connectors"]} 箭头连线)')
|
||
for m in errs:
|
||
print(f' ERROR {m}')
|
||
for m in warns:
|
||
print(f' WARNING {m}')
|
||
if not errs and not warns:
|
||
print(' 通过：箭头落点、框重叠、框间距均无异常')
|
||
|
||
total_err = sum(1 for r in results for lv, _ in r['issues'] if lv == 'ERROR')
|
||
total_warn = sum(1 for r in results for lv, _ in r['issues'] if lv == 'WARNING')
|
||
if not args.json:
|
||
print(f'\n汇总：{total_err} 个 ERROR，{total_warn} 个 WARNING，'
|
||
f'共 {len(results)} 个文件')
|
||
return 1 if (total_err or (args.strict and total_warn)) else 0
|
||
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|