Files

T

broccoliandClaude Sonnet 5 1d17b5e20d 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>

2026-07-26 18:32:25 +08:00

5.9 KiB

Raw Blame History

配置说明

本文档只覆盖当前代码中实际可用的配置。完整键集合以 backend/core/config.py 的 KNOWN_CONFIG_KEYS 为准。

配置来源和优先级

CLI 入口 backend/wordcloud_generate_hybrid.py 的顺序：

加载 backend/core/config.py 默认值
如果传 --config，调用 apply_json_config()
调用 apply_cli_overrides()
调用 finalize_runtime_config() 派生路径、字体、输出路径
调用 set_random_seed()

服务模式下，POST /api/jobs 收到的 params JSON 会由服务层合并到任务配置，写入：

backend/service_workspace/{job_id}/config.json

之后由子进程通过 --config 读取。

前端参数映射

当前前端 TestWorkbench.tsx 提交的关键字段：

前端字段	后端配置
`seed`	`SEED`
`dataColIndex`	`DATA_COL_INDEX`
`weightColIndex`	`WEIGHT_COL_INDEX`
`fontColor`	`FONT_COLOR`
`nRepetitions`	`N_REPETITIONS`
`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`

"名单完整性"不是可关闭参数，始终是硬约束。

完整配置清单

掩膜与画布

键	默认值	说明
`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`	是否使用笔画复杂度权重

填充策略

键	默认值	说明
`N_REPETITIONS`	`1`	名单重复倍率
`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`	用户覆盖最大字号
`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_SEED`	`None`	布局顺序种子，默认继承 `SEED`

JSON 别名

apply_json_config() 支持部分小写别名：

别名	正式配置
`seed`	`SEED`
`layout_seed`	`LAYOUT_SEED`
`excel_path`	`EXCEL_PATH`
`mask_image_path`	`MASK_IMAGE_PATH`
`output_dir`	`OUTPUT_DIR`
`output_prefix`	`OUTPUT_PREFIX`
`mode`	`MODE`
`work_scale`	`WORK_SCALE`
`weight_col_index`	`WEIGHT_COL_INDEX`
`weight_col_name`	`WEIGHT_COL_NAME`
`min_font_size`	`USER_MIN_FONT_SIZE`
`max_font_size`	`USER_MAX_FONT_SIZE`
`font_color`	`FONT_COLOR`
`stroke_weights`	`ENABLE_STROKE_WEIGHTS`

CLI 覆盖只支持 parse_args() 中定义的参数，不支持 font_color 或 stroke_weights CLI 参数。

类型校验

CRITICAL_TYPE_CHECKS 中的配置类型错误会直接退出。未知配置键只告警，不会失败。

路径规则

相对路径以 backend 目录作为基准解析
输出路径会在 finalize_runtime_config() 中自动创建目录
字体先尝试项目字体，再尝试 FONT_FALLBACK_PATHS
字体不可用会直接失败并退出

5.9 KiB Raw Blame History