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:
Claude Sonnet 5
+94
-32
@@ -12,9 +12,9 @@ CLI 入口 `backend/wordcloud_generate_hybrid.py` 的顺序：
|
||||
4. 调用 `finalize_runtime_config()` 派生路径、字体、输出路径
|
||||
5. 调用 `set_random_seed()`
|
||||
|
||||
服务模式下，`POST /api/jobs` 会生成任务配置并写入：
|
||||
服务模式下，`POST /api/jobs` 收到的 `params` JSON 会由服务层合并到任务配置，写入：
|
||||
|
||||
```text
|
||||
```
|
||||
backend/service_workspace/{job_id}/config.json
|
||||
```
|
||||
|
||||
@@ -25,48 +25,110 @@ backend/service_workspace/{job_id}/config.json
|
||||
当前前端 `TestWorkbench.tsx` 提交的关键字段：
|
||||
|
||||
| 前端字段 | 后端配置 |
|
||||
| --- | --- |
|
||||
| `dataColIndex` | `DATA_COL_INDEX` |
|
||||
|----------|----------|
|
||||
| `seed` | `SEED` |
|
||||
| `dataColIndex` | `DATA_COL_INDEX` |
|
||||
| `weightColIndex` | `WEIGHT_COL_INDEX` |
|
||||
| `fontColor` | `FONT_COLOR` |
|
||||
| `nRepetitions` | `N_REPETITIONS` |
|
||||
| `strokeWeights=false` | `ENABLE_STROKE_WEIGHTS=false` |
|
||||
| `strokeWeights` | `ENABLE_STROKE_WEIGHTS` |
|
||||
| `sizeRatio` | `SIZE_RATIO` |
|
||||
| `packingEfficiency` | `PACKING_EFFICIENCY` |
|
||||
| `targetFillRatio` | `TARGET_FILL_RATIO` |
|
||||
| `userMinFontSize` | `USER_MIN_FONT_SIZE` |
|
||||
| `userMaxFontSize` | `USER_MAX_FONT_SIZE` |
|
||||
| `minReadableHeightPx` | `MIN_READABLE_HEIGHT_PX` |
|
||||
| `workScale` | `WORK_SCALE` |
|
||||
| `fillOn` | `FILL_ON` |
|
||||
| `canvasRetryMaxRounds` | `CANVAS_RETRY_MAX_ROUNDS` |
|
||||
| `canvasRetryGrowth` | `CANVAS_RETRY_GROWTH` |
|
||||
| `layoutSeed` | `LAYOUT_SEED` |
|
||||
|
||||
前端只在重复次数大于 1 时传 `N_REPETITIONS`，只在关闭笔画权重时传 `ENABLE_STROKE_WEIGHTS=false`。
|
||||
"名单完整性"不是可关闭参数，始终是硬约束。
|
||||
|
||||
## 常用配置
|
||||
## 完整配置清单
|
||||
|
||||
### 掩膜与画布
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `MODE` | `IMAGE` | 掩膜模式，`IMAGE` 或 `TEXT` |
|
||||
| `MASK_IMAGE_PATH` | `7887.png` | IMAGE 模式掩膜路径，服务模式会覆盖为上传文件路径 |
|
||||
| `IMAGE_CANVAS_MODE` | `WIDTH` | 图片掩膜缩放模式 |
|
||||
| `FILL_ON` | `BLACK` | `BLACK` 表示黑色可填，`WHITE` 表示白色可填 |
|
||||
| `EXCEL_PATH` | `四个方向汇总录取名单.xlsx` | Excel 路径，服务模式会覆盖为上传文件路径 |
|
||||
|----|--------|------|
|
||||
| `MODE` | `IMAGE` | `IMAGE` 或 `TEXT` |
|
||||
| `MASK_IMAGE_PATH` | `7887.png` | IMAGE 模式掩膜路径；服务模式会被上传文件路径覆盖 |
|
||||
| `IMAGE_CANVAS_MODE` | `WIDTH` | 图片掩膜缩放模式：`WIDTH` / `HEIGHT` / `AUTO` |
|
||||
| `FILL_ON` | `BLACK` | `BLACK` = 黑色可填，`WHITE` = 白色可填 |
|
||||
| `FILL_CORNERS` | `False` | 是否自动填充四角区域 |
|
||||
| `CORNER_FILL_RATIO` | `0.15` | 四角填充面积占画布比例 |
|
||||
| `BASE_HD_WIDTH` | `4000` | 默认高清画布宽 |
|
||||
| `BASE_HD_HEIGHT` | `4000` | 默认高清画布高 |
|
||||
| `MIN_READABLE_HEIGHT_PX` | `22` | 最小可读高度（像素） |
|
||||
| `WORK_SCALE` | `0.18` | 高清画布到运算网格的缩放比例 |
|
||||
| `CANVAS_RETRY_MAX_ROUNDS` | `1` | 画布扩大重试轮数 |
|
||||
| `CANVAS_RETRY_GROWTH` | `1.12` | 完整名单放不下时的整画布边长增长比例 |
|
||||
|
||||
### 文本掩膜（TEXT 模式）
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `MASK_TEXT` | `A` | 用作掩膜的文本 |
|
||||
| `MASK_FONT_PATH` | 项目默认字体 | 掩膜字体 |
|
||||
| `MASK_FONT_SIZE` | `3000` | 掩膜文字字号 |
|
||||
|
||||
### 数据与权重
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `EXCEL_PATH` | `四个方向汇总录取名单.xlsx` | Excel 路径；服务模式被上传文件覆盖 |
|
||||
| `DATA_COL_INDEX` | `1` | 名单列，0-based |
|
||||
| `WEIGHT_COL_INDEX` | `None` | 权重列，0-based |
|
||||
| `WEIGHT_COL_NAME` | `None` | 权重列名，优先于列索引 |
|
||||
| `REMOVE_DUPLICATES` | `False` | 是否对名单去重 |
|
||||
| `ENABLE_STROKE_WEIGHTS` | `True` | 是否在无 Excel 权重时使用笔画复杂度权重 |
|
||||
| `ENABLE_STROKE_WEIGHTS` | `True` | 是否使用笔画复杂度权重 |
|
||||
|
||||
### 填充策略
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `N_REPETITIONS` | `1` | 名单重复倍率 |
|
||||
| `SIZE_RATIO` | `2.0` | `max_font` 相对 `min_font` 的比例 |
|
||||
| `PACKING_EFFICIENCY` | `0.85` | 面积模型中的打包效率 |
|
||||
| `MIN_ACCEPT_FILL_RATIO` | `0.75` | 填充率重试阈值 |
|
||||
| `REQUIRE_ALL_WORDS` | `True` | 搜索阶段是否优先要求达到目标词数 |
|
||||
| `TARGET_FILL_RATIO` | `0.45` | 面积模型目标笔画填充率 |
|
||||
| `SIZE_RATIO` | `2.0` | `max_font` 相对 `min_font` 的比例；`1.0` 为等字号模式 |
|
||||
| `PACKING_EFFICIENCY` | `0.9` | 面积模型中的打包效率 |
|
||||
|
||||
### 字号硬约束
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `USER_MIN_FONT_SIZE` | `None` | 用户覆盖最小字号 |
|
||||
| `USER_MAX_FONT_SIZE` | `None` | 用户覆盖最大字号 |
|
||||
| `FONT_SCALE_MIN` | `0.5` | 二分搜索缩放下限 |
|
||||
| `FONT_SCALE_MAX` | `1.2` | 二分搜索缩放上限 |
|
||||
| `LIMIT_LARGE_FONTS` | `True` | 是否限制大字号数量 |
|
||||
| `LARGE_FONT_LIMIT_RATIO` | `0.2` | 大字号数量上限占比 |
|
||||
| `LARGE_FONT_THRESHOLD_RATIO` | `0.8` | 超过有效最大字号该比例视为大字号 |
|
||||
| `LARGE_FONT_CAP_RATIO` | `0.6` | 超过大字号限制后的降级比例 |
|
||||
| `ENABLE_DOT_MATRIX` | `False` | 是否用点阵补偿空白区域 |
|
||||
| `CANVAS_RETRY_MAX_ROUNDS` | `1` | 画布扩大重试轮数 |
|
||||
| `MIN_FONT_FLOOR` | `2` | 绝对字号下限 |
|
||||
|
||||
### 字体与配色
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `WC_FONT_PATH` | 项目默认字体 | 布局字体 |
|
||||
| `FONT_FALLBACK_PATHS` | 系统字体列表 | 字体回退路径 |
|
||||
| `FONT_COLOR` | `#000000` | 固定字体颜色；为空时使用调色板 |
|
||||
| `DARK_COLOR_PALETTE` | 5 色深色 | `FILL_ON=WHITE` 时使用 |
|
||||
| `LIGHT_COLOR_PALETTE` | 5 色浅色 | `FILL_ON=BLACK` 时使用 |
|
||||
|
||||
### 输出
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `OUTPUT_DIR` | `.` | 输出目录 |
|
||||
| `OUTPUT_PREFIX` | `""` | 输出文件前缀 |
|
||||
| `OUTPUT_PNG` | `Efficient_Result_HD_AutoResize.png` | PNG 文件名 |
|
||||
| `OUTPUT_SVG` | `Efficient_Result_HD_AutoResize.svg` | SVG 文件名 |
|
||||
| `DB_PATH` | `wordcloud_hd.db` | SQLite 数据库文件名 |
|
||||
| `METRICS_FILE` | `metrics.json` | 指标文件名 |
|
||||
| `SAVE_DEBUG_IMAGES` | `False` | 是否保存调试图 |
|
||||
| `DEBUG_OUTPUT_DIR` | `output` | 调试文件目录 |
|
||||
|
||||
### 可复现性
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|----|--------|------|
|
||||
| `SEED` | `None` | 随机种子 |
|
||||
| `LAYOUT_ORDER_MODE` | `SORTED` | 展开序列排序模式 |
|
||||
| `LAYOUT_SEED` | `None` | 布局顺序种子，默认继承 `SEED` |
|
||||
|
||||
## JSON 别名
|
||||
@@ -74,9 +136,8 @@ backend/service_workspace/{job_id}/config.json
|
||||
`apply_json_config()` 支持部分小写别名：
|
||||
|
||||
| 别名 | 正式配置 |
|
||||
| --- | --- |
|
||||
|------|----------|
|
||||
| `seed` | `SEED` |
|
||||
| `layout_order_mode` | `LAYOUT_ORDER_MODE` |
|
||||
| `layout_seed` | `LAYOUT_SEED` |
|
||||
| `excel_path` | `EXCEL_PATH` |
|
||||
| `mask_image_path` | `MASK_IMAGE_PATH` |
|
||||
@@ -99,6 +160,7 @@ CLI 覆盖只支持 `parse_args()` 中定义的参数，不支持 `font_color`
|
||||
|
||||
## 路径规则
|
||||
|
||||
相对路径会以 `backend` 目录作为基准解析。输出路径会在 `finalize_runtime_config()` 中创建。
|
||||
|
||||
字体会先尝试项目字体，再尝试 `FONT_FALLBACK_PATHS`。字体不可用会直接失败。
|
||||
- 相对路径以 `backend` 目录作为基准解析
|
||||
- 输出路径会在 `finalize_runtime_config()` 中自动创建目录
|
||||
- 字体先尝试项目字体，再尝试 `FONT_FALLBACK_PATHS`
|
||||
- 字体不可用会直接失败并退出
|
||||
|
||||
Reference in New Issue
Block a user