Rework layout engine around exact-glyph collision, add tests and docs sync

Replace the old bbox/heuristic placement (scale search rounds, large-font
capping, stratified sampling, fill-retry ladders) with an area-model font
sizing pass feeding a C++ exact-glyph collision engine (centroid-biased
spiral + random probing, HD clearance refinement, density/hole
optimization). Simplify the frontend advanced-params panel and JobParams
type to match the surviving config surface, add a layout-constraints test
suite and a repeatable benchmark tool, and bring docs/*.md back in sync
with current code (plus new TESTING.md and DEPLOYMENT.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-26 18:32:25 +08:00
co-authored by Claude Sonnet 5
parent bf2b138007
commit 1d17b5e20d
24 changed files with 2600 additions and 1283 deletions
+15 -22
View File
@@ -23,7 +23,8 @@ wc = EfficientWordCloud(
height=600,
font_path="/path/to/font.ttf",
max_words=200,
min_font_size=8,
min_font_size=8,
max_font_size=32,
prefer_horizontal=0.9
)
@@ -36,26 +37,18 @@ img.show()
- `width` / `height`:画布尺寸。
- `font_path`:字体路径。
- `max_words`:最大词数。
- `min_font_size`:最小字体
- `prefer_horizontal`:水平排版概率。
- `use_spiral_search`:是否启用中心优先排序搜索
## 4. 并行优化的使用说明
### 4.1 Python bbox 预取
- 自动启用,无需额外配置。
- 内部使用 `ProcessPoolExecutor`,将未来词语的 bbox 计算并行化
- 运行 `generate` 时会输出预取/等待日志,便于观察并行效果
### 4.2 C++ 并行搜索
-`use_spiral_search=True` 时启用。
- 在 C++ 内部自动进行分块并行搜索,并保持中心优先排序的结果一致性。
- `min_font_size` / `max_font_size`:本次整批布局可使用的硬字号边界
- `prefer_horizontal`:水平排版概率。
- `relative_scaling`:权重对目标字号的影响比例
- `margin`:真实字形之间的最小工作网格间距。
## 4. 放置语义
- 每个词只使用权重映射得到的目标字号
- 放不下时只尝试同字号的另一方向,不会逐词缩字号
- 调用者需要检查 `layout_` 的数量;若不完整,应整批调整字号或扩大画布后创建新实例重排。
- 项目正式流水线使用 C++ `place_glyph_exact()` 做真实字形碰撞;底层兼容类保留矩形搜索 API。
## 5. 常见问题
### 5.1 为什么字体缩小时没有并行
缩小字体后 bbox 依赖当前失败状态,需要同步确认以确保正确性
### 5.2 多进程是否会导致额外内存开销?
是的,但任务仅用于 bbox 预取,且窗口大小有限,避免过度占用。
### 5.3 若没有字体文件怎么办?
会回退到 PIL 默认字体,但测量与渲染效果可能不同。
### 5.1 若没有字体文件怎么办
会回退到 PIL 默认字体,但测量与渲染效果可能不同