生成G-code SDK 文档

Appearance

SVG 配置参数 ​

SVG 元素配置（ItemType: svg） ​

SVG 元素用于描述 基于矢量路径的加工对象，适用于激光雕刻、激光切割等场景。

在调用 genGCodeByItems(items) 时，SVG 元素会作为 items 数组中的一项参与统一的 GCode 生成流程。

SVG 元素示例 ​

js
{
  itemType: 'svg',
  svgString: `<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200"><circle cx="100" cy="100" r="80" /></svg>`,
  matrix: {
    a: 1,
    b: 0,
    c: 0,
    d: 1,
    e: 0,
    f: 0,
  },
  power: 100,
  speed: 8000,
  isFill: false,
}

实际使用中，SVG 元素通常还会包含 mode 等参数，下文将对所有可用参数进行完整说明。

通用字段 ​

itemType ​

类型：'svg'

是否必填：是

说明：

声明当前元素的类型为 SVG 矢量元素。SDK 会根据该字段选择对应的解析与加工逻辑。目前该字段只有两种svg与img

svgString ​

类型：string

是否必填：是

说明：

SVG 的字符串内容，通常来源于：

  • AI 图形设计工具（如 Adobe Illustrator、Sketch, Figma）

重要限制：

  • ❌ 不支持 <text> 标签
  • ❌ 不支持 <image> 标签

SDK 目前仅支持 纯路径类 SVG，例如：

  • <path>
  • <rect>
  • <circle>
  • <ellipse>
  • <polygon>
  • <polyline>

文本应在上游阶段转换为 Path 后再传入，图像作为单独的元素配置参数后传入。

加工方式相关参数 ​

mode ​

类型：'engrave' | 'cut'

默认值：engrave

说明：

定义 SVG 元素的加工方式：

  • engrave：雕刻模式

    • 通常用于描边、轮廓雕刻、浅加工
    • 一般搭配较高速度、较低功率

  • cut：切割模式

    • 用于轮廓切割
    • 通常需要多次加工（passCount）和割缝补偿（kerfOffset）

该参数目前对 gcode 的生成没有影响，后续可根据业务需求，对不同模式增加特殊处理逻辑。

空间与变换参数 ​

matrix ​

类型：{ a: number, b: number, c: number, d: number, e: number, f: number }

是否必填：是

说明：

元素的二维仿射变换矩阵，用于描述：

  • 平移
  • 缩放
  • 旋转
  • 翻转

其含义与 SVG / Canvas 中的矩阵定义一致：

text
| a c e |
| b d f |
| 0 0 1 |

SDK 在生成 GCode 时，会先应用 matrix，一旦有了变换矩阵，就会确定元素的旋转，移动，缩放，以及尺寸，所以元素的坐标与尺寸可以不传。

加工参数 ​

power ​

类型：number

说明：

加工功率，单位百分比，范围 0–100 之间的数值。按照标准，sdk 在转换为 gcode 时，会乘 10。

speed ​

类型：number

单位：mm/min

说明：

加工速度，用于控制路径运动的进给速率，配合 G1 控制机器运动速度，单位受全局配置相关，可以被改成 每秒毫米或英寸。

passCount ​

类型：number

默认值：1

说明：

加工次数，主要用于切割场景。

当 passCount > 1 时：

  • SDK 会重复生成对应路径的 GCode

kerfOffset ​

类型：number

单位：mm

默认值：0

说明：

割缝补偿值，用于切割时修正实际加工尺寸。相当于增加一个内轮廓，或外轮廓，用于补偿切割时产生的割缝，或作轮廓切割使用。

  • 正值：向外补偿
  • 负值：向内补偿

lowerFoucus ​

类型：number

单位：mm

默认值：0

说明：

当加工该元素时，执行焦点下移动作。

填充相关参数 ​

isFill ​

类型：boolean

默认值：false

说明：

是否对 SVG 轮廓进行填充加工。

  • false：仅加工轮廓路径
  • true：对封闭路径进行内部填充

当开启填充时：

  • SDK 会根据填充算法生成内部扫描线
  • 填充算法在非闭合元素上表现较差，请确保是闭合路径

完整示例 ​

js
{
  itemType: 'svg',
  svgString: circle,
  mode: 'cut',
  matrix: { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 },
  power: 100,
  speed: 8000,
  passCount: 2,
  kerfOffset: 0.1,
  lowerFoucus: 0.2,
  isFill: false,
}