EIEI/wordcloud

Fork 0

Files

T

broccoli d5d8caef2f Initial project baseline

2026-07-04 02:40:45 +08:00

4.7 KiB

Raw Blame History

项目标准说明

本文档按当前代码整理，覆盖项目边界、运行方式、输入输出和维护约定。最后核对代码时间：2026-06-09。

项目目标

本项目生成基于名单和掩膜的词云图。后端负责读取 Excel 名单、处理掩膜、计算权重、布局、渲染和导出；前端提供参数面板、任务提交、结果查看、查找和导出入口。

当前项目不是通用设计平台。Projects、Assets、Templates 接口存在，但主要服务于当前工作台原型和素材管理，不代表完整生产级工程系统。

目录结构

路径	职责
`backend/wordcloud_generate_hybrid.py`	CLI 入口，加载配置后调用生成管线
`backend/core/config.py`	默认配置、JSON 配置合并、CLI 覆盖、路径和字体解析
`backend/core/pipeline.py`	生成主流程：读数据、画布、掩膜、权重、布局、渲染、DB、metrics
`backend/core/layout.py`	Python 布局调度、字号打分、逐词放置、SVG 导出
`backend/core/weights.py`	笔画复杂度权重、Excel 权重、面积字号模型
`backend/core/mask.py`	掩膜归一化、自动画布、边界安全 padding
`backend/core/render.py`	填充率计算和点阵补偿
`backend/EfficientWordCloud/`	C++ 扩展及其 Python 包装
`backend/service/`	FastAPI 服务、任务管理、文件存储
`frontend/src/`	React 工作台
`docs/`	标准文档入口

运行方式

一键前后端联调

在项目根目录运行：

./start-all.sh

它会：

启动 backend/start-dev.sh
启动前端 npm run dev
默认后端端口为 8000
前端 Vite 端口为 3000

单独启动后端

cd backend
./start-dev.sh

start-dev.sh 会检查 Python 依赖、必要时创建 .venv，并在 C++ 源码更新后重新编译 ewc_core。

单独启动前端

cd frontend
npm run dev

前端通过 Vite 代理访问后端。代理配置见 frontend/vite.config.ts。

CLI 生成

cd backend
python wordcloud_generate_hybrid.py --config /path/to/config.json

CLI 配置优先级：

backend/core/config.py 默认值
JSON 配置文件
CLI 参数覆盖

输入要求

Excel 名单

服务接口只接受 .xlsx。默认名单列为 DATA_COL_INDEX = 1，也就是第 2 列，索引从 0 开始。

当 REMOVE_DUPLICATES = False 时，Excel 中重复姓名会保留。当前前端默认保留重复。

权重

权重来源按优先级合并：

Excel 权重列：WEIGHT_COL_NAME 优先于 WEIGHT_COL_INDEX
笔画复杂度权重：受 ENABLE_STROKE_WEIGHTS 控制
默认权重：没有权重时使用 10

关闭 ENABLE_STROKE_WEIGHTS 且不传 Excel 权重列时，所有姓名进入均等权重。

掩膜

MODE = IMAGE 时必须提供 PNG/JPG/JPEG 掩膜。后端会将图片转灰度并以阈值 200 二值化。

FILL_ON = BLACK 时，黑色区域可填充；FILL_ON = WHITE 时，白色区域可填充。

输出产物

每次服务任务会创建：

backend/service_workspace/{job_id}/
  input/
    mask.png
    names.xlsx
  output/
    Efficient_Result_HD_AutoResize.png
    Efficient_Result_HD_AutoResize.svg
    Efficient_Result_HD_AutoResize_stroke.svg
    wordcloud_hd.db
    metrics.json
    debug/
      mask_src.png
      mask_hd.png
      mask_small.png
      occ_fast.png
  config.json

产物说明：

文件	含义
PNG	最终位图结果
SVG	填充路径 SVG
`_stroke.svg`	描边 SVG，适合继续加工
SQLite DB	`word_locations` 表，记录词语位置、字号、颜色、方向、包围盒
metrics	运行指标、画布尺寸、填充率、配置快照
debug	调试图，受 `SAVE_DEBUG_IMAGES` 控制

当前限制

重复填充当前按名单轮次展开，但单个词在放置失败时会独立降字号；这会导致后几轮整体字号小于前几轮。
reorder_stratified() 当前对主路径 query_direct() 没有实际影响，因为 query_direct() 不使用 valid_coords。
C++ Grid_query_direct 的 GIL 释放包装没有包住实际扫描调用，性能并发上还有优化空间。
API 中的 Jobs 存储在进程内存，服务重启后历史任务状态会丢失；文件仍保留在 service_workspace。
旧文档中的市场分析、路线图和性能宣传不作为当前能力承诺。

维护约定

修改算法行为时，同步更新 ALGORITHM.md。
新增或删除配置项时，同步更新 CONFIG.md。
改 HTTP 接口或响应模型时，同步更新 API.md。
不再新增单次变更记录文档；短期变更应合并进标准文档。

4.7 KiB Raw Blame History