生成G-code SDK 文档

Appearance

图片 配置参数 ​

图片元素配置（ItemType: img） ​

图片元素用于描述 基于位图（Raster）的加工对象，主要适用于激光雕刻场景。

在调用 genGCodeByItems(items) 时，图片元素会作为 items 数组中的一项，由 SDK 负责完成：

  • 图像解析与像素读取
  • 图像 → 加工路径（扫描线）转换
  • 抖动 / 灰度 / Bayer 等算法处理
  • 坐标、分辨率与加工参数的统一映射

图片元素示例 ​

js
{
  itemType: 'img',
  imgSrc: imgsrc,
  x: 60,
  y: 100,
  width: 100,
  height: 100,
  power: 100,
  speed: 6000,
  imgMode: 'Dithering',
}

实际使用中，图片元素通常还会包含 matrix、分辨率、雕刻密度等参数，下文将对所有可用字段进行完整说明。

通用字段 ​

itemType ​

类型：'img'

是否必填：是

说明：

声明当前元素为图片（位图）元素，SDK 会使用位图加工管线进行处理，而非矢量路径管线。

imgSrc ​

类型：string

是否必填：是

说明：

图片资源地址，当前版本仅支持 Base64 格式的图片字符串。 目前支持的图片格式有，png，jpg，jpeg，gif，webp。 传入的图片最好是统一png格式的灰度图，该图像格式下表现最好

常见来源包括：

  • <input type="file"> 读取后的 Base64
  • Canvas / WebGL 导出的 Base64
  • 图片编辑器处理后的结果
  • 不可以是网络图片，否则会因跨域问题导致解析失败

SDK 会在内部将图片解析为像素矩阵进行后续处理。

空间与变换参数 ​

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 会先应用 matrix，再应用全局坐标与加工模式变换。

width ​

类型：number

单位：mm

说明：

图片在画布中的宽度，

  • 以 轴对称包围盒（AABB） 的宽度为准
  • 不考虑旋转后的外接矩形

分辨率与密度参数 ​

xdpi ​

类型：number

单位：DPI

说明：

图片在 X 轴方向的分辨率，用于将像素宽度映射为实际加工尺寸。X轴每英寸多少像素点

  • 若不传，SDK 会根据 width 与图片像素宽度自动推算

ydpi ​

类型：number

单位：DPI

说明：

图片在 Y 轴方向的分辨率，用途与 xdpi 相同。Y轴每英寸多少像素点

carvingDensity ​

类型：number

单位：lines / cm

说明：

雕刻密度，表示 每厘米生成多少条扫描线。

  • 数值越大，细节越丰富
  • 数值越小，加工速度越快

该参数会直接影响：

  • 扫描线间距
  • GCode 行数
  • 实际加工时间

加工参数 ​

power ​

类型：number

单位：%

说明：

加工功率百分比，通常用于激光功率控制。

SDK 会按设备约定将该值映射到实际 GCode 指令中。

speed ​

类型：number

单位：mm/min

说明：

扫描线加工速度，对雕刻效果与效率影响较大。

passCount ​

类型：number

默认值：1

说明：

加工次数，用于重复雕刻同一图像。

  • 可用于加深雕刻效果
  • 通常不用于高精度灰度控制

engravingMode ​

类型：'single' | 'double'

默认值：double

说明：

扫描线的雕刻方向模式：

  • single：单向雕刻

    • 每行回到起点再加工
    • 精度高，但效率低

  • double：双向雕刻

    • 往返均参与加工
    • 效率高，但对设备一致性要求更高

图像处理算法 ​

imgMode ​

类型：

ts
"Jarvis" | "Floyd" | "Stucki" | "Atkinson" | "Sierra" | "Grayscale" | "Bayer";

默认值：Floyd

说明：

图像在转换为加工路径前所采用的处理算法。

抖动算法（Dithering） ​

  • Floyd（Floyd–Steinberg，默认）
  • Jarvis
  • Stucki
  • Atkinson
  • Sierra

用于将灰度图像转换为高对比度的点阵效果，

非常适合功率调节能力有限的蓝光激光设备。

其他模式 ​

  • Grayscale

    • 直接基于灰度值进行处理
    • 对激光线性响应要求较高

  • Bayer

    • 有序抖动算法
    • 规则点阵，适合特定风格图像

完整示例 ​

js
{
  itemType: 'img',
  imgSrc: imgBase64,
  matrix: { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 },
  xdpi: 254,
  ydpi: 254,
  power: 100,
  speed: 6000,
  passCount: 1,
  carvingDensity: 20,
  engravingMode: 'double',
  imgMode: 'Floyd',
}