StringArtGenerator 上手指南与核心算法概览（中文）
从零开始快速上手 Web 端 String Art 生成器，并以通俗方式介绍从图像预处理、钉子分布到贪心选线的完整生成流程。
String art（弦艺术）将“算法与手作”连接在一起：一组均匀分布在圆周上的"钉子"，通过跨钉连接的"弦"叠加，逐步重建目标图像的明暗结构。StringArtGenerator 是一个基于 Web 的生成器，你可以在浏览器中上传图片、调节参数、预览效果，并导出可制作的模板（SVG/PDF），甚至得到材料估算。本文将带你在本地快速跑起来，并用通俗方式解释核心算法。
什么是 String Art？
从形式上看，String Art 是在固定锚点间拉线形成图形；从算法上看，它是一个"用直线集合逼近灰度目标"的问题。我们在圆周上放置 N 个等间距的钉子，选择一条"线路径序列"（每相邻两点连线表示一段弦），弦的密度与覆盖次数共同决定局部明暗。生成的最小要素是：钉子坐标集与连线顺序。
项目概览与特性
- Web 端即用：无需本地原生编译，Next.js + Canvas 渲染
- OpenCV.js 预处理：灰度化、居中缩放、圆形遮罩，提升生成稳定性
- 可交互参数：pins（钉子数）、lines（线段数）、minDistance（最小跨距）、lineWeight（线权重）、linesPerTick（绘制速度）
- 实时进度：分阶段状态提示与增量绘制，便于观察效果
- 模板导出：SVG 矢量模板；材料估算含直径、针数、估算线长等
- 模板管理：可命名保存并附带预览图（本地缓存，含有效期）
快速上手（本地运行）
- 1
安装依赖
在项目根目录执行：npm i
- 2
启动开发服务器
执行：npm run dev，浏览器访问 http://localhost:3000
- 3
上传图片
在页面中选择一张对比度清晰的图片，建议主体边缘明确、背景干净
- 4
设置参数
调整 pins、lines、minDistance、lineWeight、linesPerTick；一般先定 pins，再用 lines 与 lineWeight 建立层次，用 minDistance 避免跳针过近/线束打结
- 5
开始生成
点击 Start/Generate，观察 1/4–4/4 状态提示与增量绘制进度
- 6
导出模板
打开 Export 面板，可导出 SVG，或保存 Template（可含最终预览图），并查看材料估算
选图经验：主体清晰、光照方向明确、背景简单更易得到干净结果；人像可优先选择正脸或 3/4 角度，避免低分辨率或高噪声图片。
核心算法概览（贪心 + 误差削减）
- 1
预处理（OpenCV.js）
将图片缩放至固定画布（如 500×500），转灰度并应用圆形遮罩；得到 grayscale 数组并初始化误差 error[i] = 255 - grayscale[i]。
- 2
钉子坐标
在圆周上等角度放置 pins 个锚点：x = cx + r cos(2πi/pins)，y = cy + r sin(2πi/pins)。
- 3
线段预计算
对所有可行的钉子对 (a,b) 进行 Bresenham/采样，缓存像素走向（如 lineCacheX/Y），并施加最小跨距 minDistance 约束，避免过近跳针。
- 4
贪心选线
在尚未终止前，从当前钉子出发枚举候选终点，估计该连线对误差的削减量（与 lineWeight 卷积/叠加有关），选择削减最大者作为下一条线。
- 5
增量绘制与误差更新
在 Canvas 上把该线段以 0.5px 左右线宽绘制（供预览），并将该线经过的像素在 error 中衰减；重复上述步骤直至达到 lines 条或收益不足。
- 6
模板与导出
收集 lineSequence（连线序列）与 pinCoords（钉子坐标），连同参数与元数据组装成模板；导出 SVG 或生成 PDF 制作指南（可含材料估算）。
关键参数如何影响结果
- pins（钉子数）：常见范围 150–320。越多细节越丰富，但制作难度与时间上升；入门可从 180–220 起步
- lines（线段数）：决定整体层次密度；过低会显稀疏，过高易"糊"，可在预览中微调
- minDistance（最小跨距）：限制相邻连线跨过的最小钉距，减少局部打结与反复叠线
- lineWeight（线权重）：影响单条线对误差的削减力度与可视线宽；相当于"字符串粗细/覆盖强度"
- linesPerTick（绘制速度）：仅影响 UI 绘制节奏；调高可加快预览更新，不改变最终结果
性能要点：采用固定尺寸画布（如 500×500）以控制误差表规模；对所有连线进行预计算与缓存；在绘制阶段使用 requestAnimationFrame 分帧更新，确保交互流畅。
常见问题排查（FAQ）
- OpenCV.js 正在加载：若看到相关提示，等待 1–2 秒再开始；若仍失败请刷新页面
- 结果偏"糊"：适当降低 lines 或 lineWeight，或减少 pins 并提升主体对比度
- 细节不足：提高 pins 或 lines；必要时在预处理前先对图片做轻度锐化/提亮边缘
- 导出选择：SVG 适合激光/后期编辑；PDF 指南便于打印制作（含材料估算）
- 预览与实物：实际拉线时保持一致张力、高度一致的针位和清晰的起止固定点
进一步改进方向
- 非均匀钉子分布（基于边缘/显著性自适应）
- 更鲁棒的评价函数（结合多尺度/方向敏感滤波）
- 并行化候选评估（Web Worker/OffscreenCanvas）
- 模板分享与云端图库（带参数与封面缓存）
"让算法替我们寻找路径，让双手把路径变成作品。"
— StringArtGenerator