去年秋天，我差点因为一套木雕茶盘的设计稿崩溃。屏幕上的图案完整又精致，可一送到雕刻机那边就全露馅了：线条断断续续、局部间距太窄、刀具根本进不去，最后只能删掉重来。这种事反复几次之后，我不再走“设计软件画图+导出图片+手工修路径”的老路，而是给自己写了套小而完整的项目，名字就叫 artcraft。它听起来像个手工作坊，实际上是一套从参数化图案生成、工艺约束检查、到实体文件导出的工具链。对经常和激光切割、刺绣机、CNC、木工雕刻打交道的创作者来说，它解决的是这个领域最烦人的一件事：让数字设计稿真的能变成合格实物，而不是只活在屏幕里。

1. 项目到底在做什么：从“好看”到“能做出东西”

1.1 artcraft 的核心场景：数字到实物的翻译

先说清楚一个容易被忽略的事实：设计软件里“看着没问题”和加工设备里“能顺利做出来”是两码事。你在画板里拉一条 0.1mm 的细线，打印在纸上也许看得清，但激光切割机可能直接把它烧成灰；刺绣机走针密度太高，轻则跳线重则断针；CNC 刀具是圆的，凡是内直角凹槽都要留足半径，不然刀根本切不进去。artcraft 就是在这个临界区里干活的项目。

这个项目做的事情可以归纳为三件：一是用参数化方式生成图案，二是根据你选定的工艺做可制造性检查，三是输出成对应设备能直接读取的文件格式。它不追求复杂的艺术效果，也不替你做创意决策，而是专注解决“这个图案能不能在这个材料上用这个工艺做出来”的问题。适合的人群很明确：插画师、独立手作人、创客、模型玩家，以及所有被加工参数坑过的人。

用过一段时间后，你会发现它更像一位有经验的老师傅在审图。设计师画完初稿，交给“师傅”，师傅会告诉你：这里的线太细，那里的折角要加圆角，这两个区域太密容易热累积。artcraft 干的正是这个审图师傅的活，只是它用的是几何算法而不是眼睛。

1.2 为什么没有直接用现成软件？

有人会问：Adobe Illustrator 不就能画矢量图吗？Figma 不也能导出 SVG 吗？确实能，但它们都没有把“工艺约束”这件事内置到工作流里。用这些软件完成一幅图案后，你得手动去量每段线的宽度、检查间距、补桥接点，然后到加工软件里再试一遍。如果只是做一两件作品，这样也能接受，可一旦要做系列作品、批量生成不同尺寸的图案，手动修图的时间成本就完全失控了。

市面上也有一些纹理生成器、图案生成网站，大部分偏重视觉效果，很少考虑材料厚度、刀具直径、针脚密度这些物理参数。更麻烦的是，很多生成器只能输出位图，位图一放大就糊，放到加工设备里基本等于废图。artcraft 从设计上就绕开了这个问题：内部统一用矢量路径对象，图案、检查、导出全部基于几何数据而不是像素。

还有一个现实原因：大多数手艺人不是专业编程人员，但基本都能照着示例改参数。artcraft 的交互方式因此设计成“调参”而不是“写功能”，你只需要改配置文件里的数字，而不是去理解底层几何运算。这就像开车不需要懂内燃机原理，但需要知道方向盘和油门怎么用。

1.3 项目的整体思路与模块划分

artcraft 按照功能拆成了四个模块，各模块之间只通过标准数据接口通信，避免改一处崩全盘。

第一个模块是图案生成，负责把规则网格、噪声、数学曲线这些元素组合成图案。第二个模块是工艺约束检查，它会根据你选择的工艺类型，自动识别路径中违反物理加工限制的部分。第三个模块是输出适配器，把内部对象转成 SVG、PDF、DXF 等格式，针对不同设备做单位、坐标、线宽的适配。第四个模块是预览与交互，用于实时调整参数并查看效果，减少来回试错的次数。

四者的关系可以用一个流水线来理解：生成器产出毛坯，检查器筛选废品，适配器包装成品，预览器保证你时刻知道自己在干什么。为了保证数据流通顺利，项目内部的所有尺寸都统一用毫米作为单位，所有图形对象都使用同一套路径模型。这听起来很简单，但实际很多工具链就是因为单位、坐标原点不统一而翻车。

2. 核心细节解析与实操要点

2.1 生成图案：如何让随机变得可控

做 artcraft 最初的时候，我犯过一个典型错误：为了追求“自然感”，用了大量随机函数来生成图案。结果每一版图案都像脱缰的野马，参数调整完全不可预测。后来才想明白，所谓的随机感必须建立在一个稳定的规则骨架之上，否则你根本无法判断某个参数到底是改对了还是改错了。

现在的实现方式是“种子固定 + 噪声扰动 + 规则网格”。也就是说，先用六边形、矩形或圆环网格搭好骨架，再通过噪声函数对网格顶点做位置扰动，让图案看起来有手绘般的自然变化，同时又保留了可控的结构逻辑。关键点在于随机种子必须固定。同一组参数和同一个种子，生成结果要完全一致；种子改变了，图案才变化。这样你才能对一个作品进行迭代调参，而不是每次都面对一个陌生图案。

听上去可能有点抽象，打个比方：规则网格是一首曲子的节拍，噪声则是乐手加入的即兴变化。如果节拍器时快时慢，乐队一定乱套；只有当节拍稳定时，即兴才能产生美感。参数里的“扰动幅度”就相当于乐手能发挥的自由度，调得越高，图案越活泼，但超过一定阈值就会散架。

下面是一段用 Python 给六边形网格加噪声扰动的简化示例：

import numpy as np import svgwrite def hex_grid_points(cx, cy, radius, rows, cols, jitter=0.0, seed=7): rng = np.random.default_rng(seed) points = [] for row in range(rows): for col in range(cols): x = cx + col * radius * 1.5 y = cy + row * radius * np.sqrt(3) + (col % 2) * radius * np.sqrt(3) / 2 # 扰动仅在半径方向做小幅度偏移 offset_x = rng.uniform(-jitter, jitter) offset_y = rng.uniform(-jitter, jitter) points.append((x + offset_x, y + offset_y)) return points dwg = svgwrite.Drawing('hex.svg', size=('200mm', '200mm')) for px, py in hex_grid_points(100, 100, 8, 8, 8, jitter=2.0, seed=42): dwg.add(dwg.circle(center=(px, py), r=0.5, fill='black')) dwg.save()

这个例子虽然简单，但已经把“可控随机”的核心表达出来了：用seed保证可复现，用jitter控制扰动强度，其余部分都建立在固定网格上。实际项目中，扰动对象可以从网格点扩展成路径控制点，影响的是曲线折角、开口大小、分布密度等更复杂的特征。这里要提醒一个坑：扰动幅度千万不要按网格间距的比例随意设置，最好以实际毫米为单位。比如网格间距是 10mm，jitter 设成 1mm 左右，图案既有变化又不至于结构破碎；jitter 超过 4mm，很多时候整个网格已经互相穿插，生成的路径根本没法切割。

2.2 工艺约束检查：材料物理限制如何进入代码

图案生成只是第一步，artcraft 最核心的部分其实是工艺检查。如果你没做过激光切割、刺绣、CNC 雕刻，可能会觉得这个步骤很多余；但只要试过一次，你就再也回不去了。

先说激光切割。激光切割有个致命问题：路径重叠。两个靠得很近的轮廓如果重叠了一部分，激光会在同一位置反复照射，材料就会过烧、发黑、甚至切穿。所以在检查阶段，我会用几何库对路径进行“负缓冲”检测，找出所有自相交、重叠、距离过近的线段。规则很简单：最小线距不低于 0.5mm，最好留到 0.8mm 以上；内角尽量转成圆角，因为激光束有热影响区，直角处热量集中。

再说 CNC 雕刻。CNC 用的是旋转刀具，刀具有直径，所以凹槽的最小宽度不能小于刀具直径的 1.2 倍，否则刀根本走不进去，或者会把侧壁切崩。刀具越深，这个比例还要越大。很多人第一次做雕刻件时，在软件里画了一条 1mm 宽的细槽，结果买了把 2mm 的刀，怎么对刀都没用。这类问题在 artcraft 的检查模块里会直接标红提示。

刺绣机则完全是另一个逻辑。刺绣路径不是连续的线条切割，而是一条条针迹缝合起来的。针迹太长，线容易松脱或勾到压脚；针迹太密，布料会被针孔撕裂；转弯半径太小，机针会偏离预期位置。一般情况下，棉布上的针迹长度在 2mm 到 4mm 之间比较稳妥，绣花线密度要看底布强度，越高档的底布越能承重高密度，但你真的不能拿普通棉布去跑 800 针/平方厘米的高密度图案。

我在 artcraft 的配置规则表里把这些经验值全部写成了可调整的 JSON 配置，不同工艺对应不同规则。这样每次做新图案时，不需要重新回忆这些参数，只要选择对应工艺并确认材料即可。

工艺检查的核心算法其实不复杂，但很依赖几何库。我用的是开源几何库 Shapely 来做缓冲分析、合并、求交集。比如检测两条路径是否过近，可以给一条路径做正缓冲，再看是否与另一条路径相交。下面是一个极简示例：

from shapely.geometry import LineString from shapely import buffer line_a = LineString([(0, 0), (10, 0)]) line_b = LineString([(0, 0.2), (10, 0.2)]) buf = line_a.buffer(0.5) # 0.5mm 安全距离 if buf.intersects(line_b): print("警告：两条路径过于接近，需要调整。")

如果你自己从零写，可能会遗漏三角形区域的顶点检查、路径端点连接等细节，直接用成熟的几何库是更稳妥的选择。毕竟项目重点不是算法竞赛，而是稳定地做出能加工的文件。

2.3 输出格式：为什么导出 SVG / PDF / DST 不是“另存为”

很多老手也会在导出环节栽跟头，因为不同加工软件对文件格式的解读方式完全不同。SVG 是一种矢量格式，理论上缩放不损失清晰度，但实际到加工软件里还是会出问题：坐标原点不统一、单位缺失、线宽被自动缩放、透明度信息干扰切割等。

我的建议是内部统一为“原始路径对象”，导出时才根据目标工艺生成对应文件。这样不同模块之间不必反复转换格式，也避免在中间环节丢失精度。比如 SVG 导出时，所有尺寸都以毫米为单位并写入 svg 的width和height属性；坐标原点默认放左上角，要是激光软件用的是左下角原点，就在适配器里整体做一次y = height - y变换。

PDF 导出主要用于打印和模切，导出时要注意把所有路径转成轮廓，避免因为字体、线宽设置不同导致效果差异。DXF 导出则要特别留意版本兼容性，很多老版本设备只认 R12 格式，另存为太新的版本可能会打不开。刺绣机常用的 DST 文件更是跟 SVG 完全不是一回事，它是二进制格式，记录的是一针一针的坐标和跳针指令，通常需要借助专用转换库，而不是自己在 SVG 里硬造。

3. 实操过程与核心环节实现

3.1 从零搭建 artcraft 项目骨架

我建议你从最简单的骨架开始，不要一上来就追求图形界面。先用命令行配合配置文件跑通最小闭环，再逐步加交互，这样每个环节都可验证，出了问题也知道该从哪里查。

项目目录可以按功能划分：

artcraft/ ├── config/ # 存放 YAML 配置文件 │ └── default.yaml ├── patterns/ # 图案生成脚本 │ ├── base.py │ └── hex_noise.py ├── checks/ # 工艺检查模块 │ ├── laser.py │ ├── cnc.py │ └── embroidery.py ├── output/ # 导出适配器 │ ├── svg_export.py │ └── pdf_export.py ├── preview/ # Streamlit 预览 │ └── app.py └── main.py

依赖安装非常简单，只需要四个库：numpy、svgwrite、shapely、streamlit。其中 numpy 用于数值计算，svgwrite 用于写出 SVG，shapely 用于几何分析，streamlit 用于做调参面板。听上去不多，但这套组合已经能覆盖绝大多数图案生成和导出需求了。

配置文件default.yaml长这样：

project: name: sample_embroidery size_mm: width: 200 height: 200 pattern: type: hex_noise grid_r: 8.0 jitter: 1.5 seed: 42 process: technology: embroidery fabric: cotton max_stitch_length_mm: 4.0 min_stitch_length_mm: 2.0 max_stitch_density_per_cm2: 500 output: format: svg unit: mm

这种配置方式的好处在于，图案设计与工艺参数分离。你可以把同一套图案配置用于不同工艺，只需要切换technology字段，后续检查模块就会按对应工艺规则运行。我在实际使用中经常为了一个图案分别生成激光版、刺绣版，图案参数基本不动，只改约束规则和输出格式，效率大幅提升。

3.2 完整案例一：一套可落地的刺绣纹样

以我自己做过的一组刺绣杯垫为例。目标是在直径 20cm 的圆形帆布杯垫上绣一组六边形拼贴纹样，使用五种颜色，最大针迹长度控制在 4mm 以内。

第一步，生成基础图案。我选择在圆形边界内填充六边形网格，并使用种子固定为 42 的噪声对网格点做 1.5mm 扰动，让纹理稍微有些手工感。为了避免图案超出圆形边界，每个网格点还要做一次“是否在圆内”的判断，超出部分直接裁剪。这一步看起来简单，但很关键：如果只做裁剪而不调整路径端点，最终的轮廓线会参差不齐。

第二步，工艺检查。刺绣机对针迹的约束比较严格，我看到很多新手栽在这里。检查时先统计每个区域内的针迹密度，再检查连续折线的最长线段长度。超过 4mm 的线段要打断成两段，中间补出一个 1mm 左右的短跳针，否则长针脚很容易在缝纫过程中松脱。对于需要填充的大面积色块，要使用分区填充而不是一根长线从头走到尾，这样既能减少断针风险，也能避免布面起皱。

第三步，导出。为了让刺绣软件能直接读取，我通常先生成 SVG，再导入到支持刺绣矢量转换的开源插件中做 DST 导出。第一次直接尝试导出 DST 时，我发现针迹顺序完全乱，后来才意识到 SVG 里的路径顺序决定了走针顺序，必须先按起针点最近原则重排路径。这里记一个小技巧：在导出前对所有路径做一次“旅行商式”排序，也就是让当前路径的终点尽量靠近下一条路径的起点，可以大幅减少空走针。

经过上述处理，这只杯垫从图案生成到可上机器的文件只花了十几分钟。实际绣出来的效果和屏幕预览的误差很小，最主要的原因是参数化设计从源头保证了尺寸的毫米级准确，而不是靠肉眼在软件里对着屏幕划线。

3.3 完整案例二：激光切割用的几何纹理杯垫

第二个案例是激光雕刻桦木杯垫。桦木板厚度 3mm，尺寸 120mm×120mm，目标是在中央刻一个直径 90mm 的同心圆渐变纹理，外圈留出 15mm 的空白边。

图案生成部分我用的是圆环加噪声扰动。把圆周上的点按固定角度间隔采样，同时让半径随噪声函数变化，形成类似涟漪的轮廓。由于激光雕刻是“划线”而不是“填充”，对线宽的要求主要取决于切割机光斑直径，通常在 0.1mm 到 0.3mm 之间。为了保证刻线清晰，我把最小线宽设置为 0.3mm，线条间距保持在 0.8mm 以上。

工艺检查时发现一个问题：最外圈与木坯的边缘距离只有 12mm，比预设安全边界 15mm 小了。这种小误差肉眼几乎看不出来，但切割时如果板材边缘不平整，激光路径可能会滑出材料，导致切穿。我将图案整体缩放至 80mm 直径，重新生成，安全距离恢复到了 20mm。

实际加工参数我用的是中低速、中等功率。常见的椴木层板适合用 80% 功率、150mm/s 速度先试切一条 10mm 长的线，观察发黑程度再调整。切割功率过高会留下焦边；功率太低则切不穿。这些数据不是固定的，因为激光管功率衰减、镜片清洁度都会影响效果，所以每次换材料都必须做小块试切。

3.4 让调参不再痛苦：一个非常轻的实时预览界面

很多人一听“调参”就开始皱眉，因为每次修改完参数，还要重跑脚本、打开文件、放大查看，这样反复几次就烦了。我在 project 里加了一个 Streamlit 页面，让所有关键参数变成滑动条，拖动後图案立即刷新，并且能一键导出 SVG。代码非常短，核心只有几十行：

import streamlit as st import svgwrite import numpy as np st.title("artcraft Pattern Preview") jitter = st.slider("噪声扰动 (mm)", 0.0, 4.0, 1.5, step=0.1) seed = st.slider("随机种子", 0, 100, 42) radius = st.slider("网格半径 (mm)", 2.0, 12.0, 8.0, step=0.5) if st.button("生成并导出 SVG"): dwg = svgwrite.Drawing('preview.svg', size=('200mm', '200mm')) rng = np.random.default_rng(seed) # 循环生成六边形网格并添加圆点 for row in range(10): for col in range(10): x = col * radius * 1.5 y = row * radius * np.sqrt(3) + (col % 2) * radius * np.sqrt(3) / 2 x += rng.uniform(-jitter, jitter) y += rng.uniform(-jitter, jitter) dwg.add(dwg.circle(center=(x + 20, y + 20), r=0.4, fill='black')) dwg.save() st.success("已导出 preview.svg")

把生成脚本和 Streamlit 预览结合之后，整个项目就从一个“命令行小工具”变成了半图形化工作台。实际使用时，我会把工艺检查的结果也显示在预览页面上，比如把有风险的路径标成橙色，这样一眼就能看出问题区域。

4. 常见问题与排查技巧实录

4.1 屏幕上完美，实物却变形失真

这种情况我遇到太多次，后来总结了三个主要原因。第一，单位混淆。SVG 里有的长度没有写单位，某些软件默认看成像素，某些软件默认看成毫米，结果同一张图在不同设备里大小完全不同。解决办法是把所有内部尺寸统一为毫米，导出时在 SVG 根节点显式写入width="200mm"和height="200mm"。第二，坐标系方向。屏幕坐标系的 y 轴向下，数学坐标系的 y 轴向上，很多加工软件采用后者。如果直接把 SVG 原样导入，图案会垂直翻转，雕刻出来恰好镜像。所以导出时我会多写一个可选参数，控制是否翻转 y 轴。第三，位图预览误导。预览图是自动生成的位图，放大后会模糊，但加工文件是矢量，精度完全足够；问题在于加工软件导入位图后会自动做一次采样，可能造成路径偏移。最佳实践是先打印一份 1:1 的纸样，再用材料试切，千万不要跳过这一步。

4.2 激光切割总是烧焦、切穿

如果你发现切割边缘发黄发黑，或者某些区域直接熔穿，大概率不是功率设置问题，而是路径重叠。同一个位置被激光走了两遍，热量叠加，材料自然会过烧。排查方法很简单：把 SVG 导入到图形软件里，放大看轮廓线，找有没有完全重合或交叉的线段。手动找太烦，我一般直接用 Shapely 的unary_union合并所有路径，再对比合并前后的总路径长度；如果长度明显减少，说明有重叠被合并了，这时就需要重新生成或手动修路径。还有一种情况是嵌套切割时，两个相邻对象间距太小，切割热影响区相互叠加。这时候不要硬调，直接把图案间距拉开到 3mm 以上，效果立竿见影。

4.3 刺绣机频繁断针、跳线

断针跳线的原因很多，但最常见的还是针迹长度和密度不合理。针迹太长，线在布面形成浮长线，容易挂住压脚；针迹太短太密，针眼反复扎同一区域，布料纤维断裂，线也容易被扯断。排查时先做一个小样：在同样的底布上分别以 2mm、3mm、4mm 针迹长度跑三条线，观察哪种长度最稳定。密度方面，如果图案色块面积大，尽量用分区填充，每区间隔 1mm 以上，不要用一根长线横跨整个图案。另外别忘了检查底布张力，我遇到过好几次断针，最后发现是绣花框绷得太松，布料在针板上来回晃动，导致针尖偏离针孔。这类机械问题听起来笨，但实际发生率相当高。

4.4 故障速查表与工作流检查清单

我把这些经验做成了一张速查表，建议你也维护一份属于自己设备的版本，因为每台机器的状态都有细微差别，表格里的数值只能作为起点，而不是终点。

每次开工前，我会固定走一遍五步检查清单：第一步定尺寸，明确加工材料的实际长宽；第二步生成图案，确认随机种子和扰动参数；第三步工艺检查，查看风险报告；第四步导出测试文件，先用便宜材料做一小块试加工；第五步记录结果，拍照并填写参数笔记。这套流程不是说每次都能一次成功，但能保证如果出了问题，你永远知道是在哪一步发生的。

这个项目我断断续续改了大半年，最大的收获并不是工具本身，而是我终于能在开机之前预判到那些曾经反复出现的翻车现场。对了，最后分享一个很土但很管用的技巧：在 artcraft 的目录里建一个试错记录.txt，每完成一件作品就把参数、材料、加工结果随手记进去。三个月后回看，你会比任何一本教程都更了解自己的设备与习惯。到现在我依然在持续改这套工具，但每次动代码之前，先翻一翻那份记录，总能少踩几个坑。