生成G-code SDK 文档

Appearance

全局 API ​

将 SDK 实例化 ​

js
const maker = new GCodeSDK.GCodeMaker(globalConfig);

GCodeMaker 是整个 SDK 的核心入口，用于管理全局加工配置、坐标体系、加工模式以及 GCode 的整体结构。

实例化时需要传入一个 全局配置对象（globalConfig），以下将对 globalConfig 中的每一个参数进行详细说明。

globalConfig 的默认值:

js
{
  gcodeHeader: ["G00 G17 G40 G21 G54", "G90", "M4"],
  gcodeFooter: ["M9", "G1 S0", "M5", "G90", "M2"],
  startPointType: "absolute",
  workMode: "flat",
};

实例化方法 genGCodeByItems() ​

js
const maker = new GCodeSDK.GCodeMaker(globalConfig);
const items = [
  { itemType: "svg", svgString: circleSvgContent, power: 100, speed: 8000 },
];
maker.genGCodeByItems(items).then((gcodeArr) => {
  console.log(gcodeArr, "生成的 img 与 svg gcode");
  maker.downloadGCodeFile(gcodeArr);
  console.timeEnd("生成gcode");
});

genGCodeByItems 是 SDK 的核心方法，传入一个数组，数组内的每一个元素代表一个加工内容，SDK 会根据这些内容生成对应的 GCode 指令。 items的接口参考 svg 与图片的数据结构。

gcodeHeader ​

类型：string[]

是否必填：否（有默认值）

说明：

gcodeHeader 用于定义 加工开始前 自动插入到 GCode 顶部的指令集合，通常用于：

  • 设备初始化
  • 单位设置（mm / inch）
  • 坐标模式设置（G90 / G91）
  • 激光 / 主轴初始化

SDK 内部提供了一套通用默认值，适用于大多数桌面级激光或数控设备。如果你的设备有特殊需求，可以通过该参数覆盖默认行为。

示例：

js
gcodeHeader: [
  "G21", // 使用毫米单位
  "G90", // 绝对坐标模式
  "M4", // 激光动态功率模式
];

注意事项：

  • 传入 string[] 时，SDK 会按顺序逐行输出
  • 若不传，将使用 SDK 内置默认 Header

gcodeFooter ​

类型： string[]

是否必填：否（有默认值）

说明：

gcodeFooter 用于定义 加工结束后 自动追加到 GCode 尾部的指令，通常用于：

  • 激光 / 主轴关闭
  • 回零或抬刀
  • 释放电机、结束任务

示例：

js
gcodeFooter: [
  "M5", // 关闭激光
  "G0 X0 Y0", // 回到原点
];

设计目的：

将「加工内容」与「设备收尾逻辑」解耦，避免在每个算法模块中重复处理收尾指令。

startPointType ​

类型：'relative' | 'absolute'

默认值：absolute

是否必填：否

说明：

定义整个加工任务的 起始点坐标策略。

relative（相对起点） ​

  • 所有路径将基于内容自身的包围盒计算
  • SDK 会自动将图形的左下角（或约定起点）映射到设备当前坐标
  • 适合 UI 编辑器、图形拼接、批量排版等场景
  • 对标lightburn 的从当前位置开始加工

absolute（绝对坐标，默认） ​

  • 所有坐标将直接使用图形计算后的绝对值
  • 不做额外的起点平移
  • 适合工业设备、固定工装、已知零点的加工场景

示例：

js
startPointType: "absolute";

注意事项：

  • absolute 模式下，需确保设备零点与设计坐标一致
  • 与 gcodeHeader 中的 G90 / G91 设置逻辑相互独立

workMode ​

类型：'flat' | 'rotary'

默认值：flat

是否必填：否

说明：

定义 SDK 的 加工平面模式，该参数会直接影响坐标系统、路径展开方式以及后续算法行为。

flat（平面模式，默认） ​

  • 标准 XY 平面加工
  • 适用于激光切割、雕刻、CNC 平面加工
  • 所有图形均按二维坐标处理

rotary（旋转配件模式） ​

  • 用于圆柱体、滚轴类物体的展开加工
  • SDK 会将平面路径映射为「线性位移 + 旋转轴位移」
  • 启用该模式后，必须同时配置 rotaryMode对象
  • 需要输入的参数与lightburn 旋转模式保持一致

示例：

js
workMode: "rotary";

rotaryMode ​

类型：Object

是否必填：

  • 当 workMode === 'rotary' 时：必填
  • 其他模式下：忽略

说明：

rotaryMode 用于描述 旋转配件的物理参数与运动方式，SDK 会根据这些参数完成：

  • 平面 → 圆柱展开映射
  • 线性距离与角度 / 旋转轴位移之间的换算

rotaryMode.axis ​

类型：'Z' | 'A' | 'Y'

说明：

指定设备上用于旋转的轴。

  • A：最常见的第四轴定义
  • Z / Y：部分设备会复用现有轴作为旋转轴

示例：

js
rotaryMode: {
  axis: "A";
}

rotaryMode.rotaryType ​

类型：'chuck' | 'roller'

说明：

定义旋转配件的结构类型，不同结构会影响距离换算方式。

  • chuck（卡爪）

    • 物体固定在旋转轴中心
    • 以物体直径为核心参数

  • roller（滚筒）

    • 物体通过滚筒带动旋转
    • 需要额外考虑滚筒直径

rotaryMode.rotationDistance ​

类型：number

单位：mm

说明：

定义 旋转轴转一整圈所对应的线性位移。

该参数通常由设备固件或厂家提供，用于精确计算：

线性距离(mm) ↔ 旋转角度(°)

示例：

js
rotationDistance: 360;

rotaryMode.rollerDiameter ​

类型：number

单位：mm

适用条件：仅当 rotaryType === 'roller'

说明：

滚筒本身的直径，用于计算物体实际旋转角度。

SDK 会综合：

  • rollerDiameter
  • objectDiameter

来修正因接触半径不同带来的误差。

rotaryMode.objectDiameter ​

类型：number

单位：mm

说明：

被加工物体的实际直径，是旋转展开计算中的核心参数之一。

  • 对 chuck 模式：直接用于周长计算
  • 对 roller 模式：与滚筒直径共同决定实际旋转比例
js
const maker = new GCodeSDK.GCodeMaker({
  gcodeHeader: ["G21", "G90", "M4"],
  gcodeFooter: ["M5", "G0 X0 Y0"],
  startPointType: "relative",
  workMode: "rotary",
  rotaryMode: {
    axis: "A",
    rotaryType: "roller",
    rotationDistance: 360,
    rollerDiameter: 20,
    objectDiameter: 60,
  },
});