Initial project baseline

2026-07-04 02:40:45 +08:00
commit d5d8caef2f
86 changed files with 15590 additions and 0 deletions
@@ -0,0 +1,66 @@
+# EfficientWordCloud Core / 核心引擎
+
+(English below)
+
+## 🇨🇳 中文说明
+
+**EfficientWordCloud** 是本项目的高性能 C++ 核心扩展库。它负责处理最耗时的碰撞检测和空间搜索任务，是生成 4K/8K 超高清词云的基础。
+
+### 核心技术
+1. **积分图 (Integral Image)**：
+   使用 O(1) 时间复杂度计算任意矩形区域的像素和。这意味着无论单词多大，碰撞检测的耗时都是恒定的，实现了瞬时检测。
+2. **螺旋搜索 (Spiral Search)**：
+   替代传统的随机尝试算法，采用“从中心向外”的螺旋扫描策略。这不仅大幅提高了填充率，还将大图生成速度提升了 **50-100 倍**。
+3. **空间索引 (Spatial Indexing)**：
+   内部维护一个层级网格，快速剔除无效区域。
+
+### 依赖说明
+- 核心扩展包依赖：`numpy`、`pillow`、`matplotlib`
+- 主脚本额外依赖：`pandas`（用于 `wordcloud_generate_hybrid.py` 读取 Excel）
+
+安装示例：
+```bash
+pip install numpy pillow matplotlib
+# 如果你要运行仓库根目录主脚本，再额外安装：
+pip install pandas
+```
+
+### 编译安装
+在当前目录下运行以下命令，将在 `efficient_wordcloud` 文件夹中生成编译好的扩展文件（`.so` 或 `.pyd`）：
+
+```bash
+python3 setup.py build_ext --inplace
+```
+
+### 性能对比
+| 分辨率 | 原版 wordcloud | EfficientWordCloud (Spiral) | 提速 |
+| :--- | :--- | :--- | :--- |
+| 1920x1080 | ~2.5s | ~0.05s | **50x** |
+| 8000x4000 | ~60s+ | ~0.5s | **120x+** |
+
+---
+
+## 🇺🇸 English Description
+
+**EfficientWordCloud** is the high-performance C++ backend for this project. It handles the computationally expensive collision detection and spatial queries, enabling the generation of 4K/8K ultra-HD word clouds.
+
+### Key Technologies
+1. **Integral Images**:
+   Calculates the sum of pixels in any rectangular area in O(1) time. This allows for instantaneous collision checks regardless of the word size.
+2. **Spiral Search**:
+   Replaces the brute-force random sampling with a "Center-Out" spiral heuristic. This significantly improves packing density and boosts performance by **50-100x** on large canvases.
+3. **Spatial Indexing**:
+   Maintains an internal hierarchical grid to quickly cull invalid regions.
+
+### Build & Install
+Run the following command in this directory to build the extension in-place (generates `.so` or `.pyd` inside `efficient_wordcloud` folder):
+
+```bash
+python3 setup.py build_ext --inplace
+```
+
+### Performance Comparison
+| Resolution | Original Library | EfficientWordCloud (Spiral) | Speedup |
+| :--- | :--- | :--- | :--- |
+| 1920x1080 | ~2.5s | ~0.05s | **50x** |
+| 8000x4000 | ~60s+ | ~0.5s | **120x+** |